عیب‌یابی

برای اطلاعات بیشتر می‌توانید به راهنمای عیب‌یابی Rollup نیز مراجعه کنید.

اگر پیشنهادات ارائه‌شده در این صفحه کار نمی‌کنند، لطفاً سؤالات خود را در GitHub Discussions یا در کانال ‎#help در Vite Land Discord ارسال کنید.

CJS

Vite CJS Node API deprecated

نسخه CJS از رابط کاربری Node در Vite منسوخ شده و در Vite 6 حذف خواهد شد. برای جزئیات بیشتر، این بحث در GitHub را مشاهده کنید. توصیه می‌شود فایل‌ها یا فریمورک‌های خود را به نسخه ESM Vite به‌روزرسانی کنید.

در یک پروژه ابتدایی Vite، اطمینان حاصل کنید:

1. محتوای فایل vite.config.js از سینتکس ESM استفاده می‌کند.
2. فایل package.json باید شامل "type": "module" باشد، یا به‌جای آن، از پسوند ‎.mjs یا ‎.mts برای فایل‌های خود استفاده کنید، مثلاً vite.config.mjs یا vite.config.mts.

برای پروژه‌های دیگر، چندین رویکرد عمومی وجود دارد:

• پیکربندی ESM به‌عنوان پیش‌فرض، انتخاب CJS در صورت نیاز: اضافه‌کردن "type": "module" به package.json پروژه. تمام فایل‌های ‎*.js اکنون به‌عنوان ESM تفسیر می‌شوند و باید از سینتکس ESM استفاده کنند. می‌توانید با تغییر نام فایل به پسوند ‎.cjs از CJS استفاده کنید.
• نگه‌داشتن CJS به‌عنوان پیش‌فرض، انتخاب ESM در صورت نیاز: اگر package.json پروژه دارای "type": "module" نیست، تمام فایل‌های ‎*.js به‌عنوان CJS تفسیر می‌شوند. می‌توانید با تغییر نام فایل به پسوند ‎.mjs از ESM استفاده کنید.
• ایمپورت کردن داینامیک Vite: اگر همچنان نیاز به استفاده از CJS دارید، می‌توانید Vite را به‌صورت داینامیک با استفاده از import('vite') ایمپورت کنید. این کار نیاز دارد که کد شما در یک کانتکست async نوشته شود، اما همچنان قابل مدیریت است، زیرا بیشتر APIهای Vite به‌صورت ناهمزمان (asynchronous) کار می‌کنند.

اگر نمی‌دانید هشدار از کجا می‌آید، می‌توانید اسکریپت خود را با فلگ VITE_CJS_TRACE=true اجرا کنید تا تریس استک را لاگ کند:

VITE_CJS_TRACE=true vite dev

اگر می‌خواهید موقتاً هشدار را نادیده بگیرید، می‌توانید اسکریپت خود را با فلگ VITE_CJS_IGNORE_WARNING=true اجرا کنید:

VITE_CJS_IGNORE_WARNING=true vite dev

توجه داشته باشید که فایل‌های پیکربندی postcss هنوز از ESM + TypeScript (‎.mts یا ‎.ts در ‎"type": "module"‎) پشتیبانی نمی‌کنند. اگر پیکربندی‌های postcss با ‎.ts دارید و "type": "module" را به package.json اضافه کرده‌اید، همچنین باید پیکربندی postcss را به ‎.cts تغییر نام دهید.

CLI

Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'‎

مسیر پوشه پروژه شما ممکن است شامل & باشد، که با npm در ویندوز کار نمی‌کند (npm/cmd-shim#45).

شما نیاز خواهید داشت به:

• تغییر به یک پکیج منیجر دیگر (مانند pnpm, yarn)
• حذف & از مسیر پروژه شما

پیکربندی

این پکیج ESM Only است

هنگام ایمپورت کردن یک پکیج ESM Only با require، خطای زیر رخ می‌دهد.

Failed to resolve "foo". This package is ESM only but it was tried to load by `require`.

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/dependency.js from /path/to/vite.config.js not supported.

Instead change the require of index.js in /path/to/vite.config.js to a dynamic import() which is available in all CommonJS modules.

در Node.js نسخه‌های 22 و پایین‌تر، به‌طور پیش‌فرض فایل‌های ESM نمی‌توانند با استفاده از require بارگذاری شوند.

اگرچه ممکن است با استفاده از گزینه ‎--experimental-require-module، یا در نسخه‌های بالای 22 در Node.js یا در رانتایم‌های دیگر این کار امکان‌پذیر باشد، اما همچنان توصیه می‌کنیم که پیکربندی خود را به ESM تبدیل کنید به یکی از روش‌های زیر:

• اضافه‌کردن "type": "module" به package.json
• تغییر نام vite.config.js/vite.config.ts به vite.config.mjs/vite.config.mts

سرور توسعه

Requests are stalled forever

اگر از لینوکس استفاده می‌کنید، ممکن است محدودیت‌های توصیف‌گر فایل (file descriptor) و محدودیت‌های inotify باعث این مشکل شوند. ازآنجاکه Vite بیشتر فایل‌ها را باندل نمی‌کند، مرورگرها ممکن است درخواست‌های زیادی ارسال کنند که نیاز به توصیف‌گر فایل زیادی دارند، و این باعث افزایش محدودیت می‌شود.

برای حل این مشکل:

• افزایش محدودیت دیسکریپتر فایل با ulimit

  # بررسی محدودیت فعلی
  $ ulimit -Sn
  # تغییر محدودیت (موقتی)
  $ ulimit -Sn 10000 # ممکن است نیاز به تغییر محدودیت سخت نیز داشته باشید
  # راه‌اندازی مجدد مرورگر خود

• افزایش محدودیت‌های مرتبط با inotify با sysctl

  # بررسی محدودیت‌های فعلی
  $ sysctl fs.inotify
  # تغییر محدودیت‌ها (موقتی)
  $ sudo sysctl fs.inotify.max_queued_events=16384
  $ sudo sysctl fs.inotify.max_user_instances=8192
  $ sudo sysctl fs.inotify.max_user_watches=524288

اگر مراحل بالا کار نکرد، می‌توانید DefaultLimitNOFILE=65536 را به‌عنوان یک پیکربندی غیرکامنت به فایل‌های زیر اضافه کنید:

• ‎/etc/systemd/system.conf
• ‎/etc/systemd/user.conf

برای لینوکس Ubuntu، ممکن است نیاز به اضافه‌کردن خط ‎* - nofile 65536 به فایل ‎/etc/security/limits.conf به‌جای به‌روزرسانی فایل‌های پیکربندی systemd داشته باشید.

توجه داشته باشید که این تنظیمات پایدار هستند اما نیاز به راه‌اندازی مجدد دارند.

به‌طور جایگزین، اگر سرور داخل یک devcontainer در VS Code در حال اجرا است، ممکن است به‌نظر برسد که درخواست‌ها متوقف شده‌اند. برای رفع این مشکل، به بخش Dev Containers / VS Code Port Forwarding مراجعه کنید.

Network requests stop loading

هنگام استفاده از یک گواهی SSL خودامضا، Chrome تمام دستورات کش را نادیده می‌گیرد و محتوا را دوباره بارگذاری می‌کند. Vite به این دستورات کش متکی است.

برای حل این مشکل از یک گواهی SSL معتبر استفاده کنید.

یا میتوانید به این لینک ها مراجعه کنید: مشکلات کش، مشکل Chrome

macOS

می‌توانید یک گواهی معتبر را از طریق CLI با این فرمان نصب کنید:

security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer

یا با واردکردن آن به اپلیکیشن Keychain Access و به‌روزرسانی اعتماد گواهی خود به "Always Trust"

431 Request Header Fields Too Large

هنگامی که سرور / سرور WebSocket یک هدر HTTP بزرگ دریافت می‌کند، درخواست رد شده و هشدار زیر نمایش داده می‌شود.

Server responded with status code 431. See https://vite.dev/guide/troubleshooting.html#_431-request-header-fields-too-large.

این به این دلیل است که Node.js اندازه هدر درخواست را برای کاهش CVE-2018-12121 محدود می‌کند.

برای اجتناب از این مشکل، سعی کنید اندازه هدر درخواست خود را کاهش دهید. به عنوان مثال، اگر کوکی طولانی است، آن را حذف کنید. یا می‌توانید از ‎--max-http-header-size برای تغییر حداکثر اندازه هدر استفاده کنید.

Dev Containers / انتقال پورت VS Code

اگر از Dev Container یا قابلیت انتقال پورت در VS Code استفاده می‌کنید، ممکن است نیاز به تنظیم گزینه server.host به 127.0.0.1 در تنظیمات داشته باشید تا کار کند.

این به این دلیل است که قابلیت انتقال پورت در VS Code از IPv6 پشتیبانی نمی‌کند.

برای جزئیات بیشتر، به ‎#16522 مراجعه کنید.

HMR

Vite تغییر فایل را تشخیص می‌دهد اما HMR کار نمی‌کند

ممکن است فایلی را با یک حالت متفاوت ایمپورت کنید. به عنوان مثال، src/foo.js وجود دارد و src/bar.js شامل:

import './Foo.js' // باشد './foo.js' باید

لینک ارور: ‎#964

Vite تغییر فایل را تشخیص نمی‌دهد

اگر از Vite در محیط WSL2 استفاده می‌کنید، در برخی شرایط Vite قادر به نظارت بر تغییرات فایل‌ها نخواهد بود. برای اطلاعات بیشتر به گزینه server.watch مراجعه کنید.

به‌جای HMR، بارگذاری کامل انجام می‌شود

اگر HMR توسط Vite یا پلاگینی مدیریت نشود، بارگذاری کامل انجام خواهد شد زیرا این تنها راه برای تازه‌سازی برنامه است.

اگر HMR مدیریت شود، اما در داخل یک وابستگی حلقه‌ای قرار داشته باشد، یک بارگذاری کامل نیز برای بازیابی ترتیب اجرای برنامه رخ خواهد داد. برای حل این مشکل، سعی کنید حلقه وابستگی را بشکنید. اگر تغییر فایلی باعث این مشکل شده است، می‌توانید دستور vite --debug hmr را اجرا کنید تا مسیر وابستگی حلقه‌ای ثبت شود.

بیلد

فایل بیلد شده به دلیل خطای CORS کار نمی‌کند

اگر فایل HTML خروجی با پروتکل file باز شود، اسکریپت‌ها با خطای زیر مواجه شده و اجرا نخواهند شد.

Access to script at 'file:///foo/bar.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///foo/bar.js. (Reason: CORS request not http).

برای اطلاعات بیشتر در مورد اینکه چرا این اتفاق می‌افتد، به Reason: CORS request not HTTP - HTTP | MDN مراجعه کنید.

شما باید به فایل با پروتکل http دسترسی پیدا کنید. آسان‌ترین راه برای انجام این کار اجرای npx vite preview است.

وابستگی‌های بهینه‌سازی‌شده

لینک شدن پکیج های قدیمی به پکیج های لوکال

کلید هش استفاده‌شده برای باطل کردن وابستگی‌های بهینه‌شده بستگی به محتوای package lock، وصله‌های اعمال‌شده به وابستگی‌ها و گزینه‌های موجود در فایل پیکربندی Vite که بر روی باندل ماژول‌های نود تأثیر می‌گذارد، دارد. این به این معنی است که Vite وقتی یک وابستگی با استفاده از ویژگی‌ای مانند overrides npm بازنویسی می‌شود، آن را شناسایی خواهد کرد و وابستگی‌های شما را در شروع بعدی سرور دوباره باندل می‌کند. Vite وقتی که از ویژگی‌ای مانند npm link استفاده می‌کنید، وابستگی‌ها را باطل نمی‌کند. در صورت لینک یا unlink یک وابستگی، باید بهینه‌سازی مجدد را در شروع بعدی سرور با استفاده از vite --force انجام دهید. ما توصیه می‌کنیم از overrides استفاده کنید که اکنون توسط همه پکیج منیجرها پشتیبانی می‌شود (همچنین به pnpm overrides و yarn resolutions مراجعه کنید).

گلوگاه‌های عملکرد

اگر به‌دلیل گلوگاه‌های عملکرد اپلیکیشن با زمان بارگذاری کند مواجه شدید، می‌توانید با سرور توسعه Vite یا هنگام ساخت اپلیکیشن، بازرسی کننده Node.js را فعال کنید تا پروفایل CPU ایجاد کنید:

سرور توسعه

vite --profile --open

ساخت

vite build --profile

سرور توسعه Vite

پس از باز شدن اپلیکیشن در مرورگر، فقط صبر کنید تا بارگذاری کامل شود و سپس به ترمینال برگردید و کلید p را فشار دهید (بازرسی کننده Node.js را متوقف می‌کند) سپس کلید q را فشار دهید تا سرور توسعه متوقف شود.

بازرسی کننده Node.js فایل vite-profile-0.cpuprofile را در پوشه اصلی ایجاد می‌کند، به https://www.speedscope.app بروید و پروفایل CPU را با استفاده از دکمه BROWSE بارگذاری کنید تا نتیجه را بررسی کنید.

می‌توانید vite-plugin-inspect را نصب کنید که به شما اجازه می‌دهد وضعیت میانی پلاگین‌های Vite را بازرسی کنید و همچنین به شما کمک می‌کند تا مشخص کنید کدام پلاگین‌ها یا میان‌افزارها در اپلیکیشن‌های شما گلوگاه هستند. این پلاگین می‌تواند در حالت‌های توسعه و ساخت استفاده شود. فایل readme را برای جزئیات بیشتر بررسی کنید.

سایر موارد

ماژول خارجی برای سازگاری با مرورگر

هنگامی که از یک ماژول Node.js در مرورگر استفاده می‌کنید، Vite هشدار زیر را خروجی می‌دهد.

Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.

این به این دلیل است که Vite به‌صورت خودکار ماژول‌های Node.js را پلی‌فیل نمی‌کند.

ما توصیه می‌کنیم از ماژول‌های Node.js برای کد مرورگر اجتناب کنید تا اندازه بسته کاهش یابد، اگرچه می‌توانید پلی‌فیل‌ها را به‌صورت دستی اضافه کنید. اگر ماژول از یک کتابخانه شخص ثالث وارد شده است (که قرار است در مرورگر استفاده شود)، توصیه می‌شود که مشکل را به پشتیبانی کتابخانه مربوطه گزارش دهید.

خطای سینتکس / Type Error رخ می‌دهد

Vite نمی‌تواند کدی را که فقط در non-strict mode اجرا می‌شود (حالت غیر-سخت‌گیر) را مدیریت کند و از آن پشتیبانی نمی‌کند. این به این دلیل است که Vite از ESM استفاده می‌کند و همیشه Strict Mode درون ESM فعال است.

برای مثال، ممکن است این خطاها را ببینید.

[ERROR] With statements cannot be used with the "esm" output format due to strict mode

TypeError: Cannot create property 'foo' on boolean 'false'

اگر این کدها درون وابستگی‌ها استفاده می‌شوند، می‌توانید از patch-package (یا yarn patch یا pnpm patch) برای یک راه‌فرار استفاده کنید.

افزونه‌های مرورگر

برخی از افزونه‌های مرورگر (مانند مسدودکننده‌های تبلیغات) ممکن است از ارسال درخواست‌ها از کلاینت Vite به سرور توسعه Vite جلوگیری کنند. در این صورت، ممکن است صفحه سفید بدون خطاهای ثبت‌شده مشاهده کنید. اگر با این مشکل روبه‌رو هستید، امتحان کنید که افزونه‌ها را غیرفعال کنید.

لینک‌های cross drive در ویندوز

اگر در پروژه شما لینک‌های cross drive وجود داشته باشد، Vite ممکن است کار نکند.

یک مثال از لینک‌های cross drive:

• یک درایو مجازی که با دستور subst به یک پوشه لینک شده است
• یک symlink/junction به یک درایو متفاوت با دستور mklink (مثال: کش global Yarn)

لینک ارور: ‎#10802