---
url: /guide/api-environment.md
---
# Environment API

:::warning آزمایشی
رابط Environment API هنوز در مرحله‌ی آزمایشی (experimental) هست. با این حال، ما تلاش می‌کنیم بین نسخه‌های اصلی (major) پایداری این APIها را حفظ کنیم تا جامعه‌ی توسعه‌دهندگان بتوانند با آن‌ها کار کرده و تجربیات خود را بر اساس آن‌ها توسعه دهند. ما قصد داریم این APIهای جدید را در یکی از نسخه‌های اصلی آینده به حالت پایدار (stable) برسانیم. البته ممکن است در این فرآیند تغییرات شکننده (breaking changes) نیز اعمال شود، اما این کار زمانی انجام خواهد شد که پروژه‌ها و کتابخانه‌های وابسته فرصت کافی برای آزمایش و ارزیابی این قابلیت‌های جدید را داشته باشند.

منابع:

* [بحث و گفتگو](https://github.com/vitejs/vite/discussions/16358) جایی که ما در حال جمع‌آوری نظرات درباره APIهای جدید هستیم.
* [PR مربوط به Environment API](https://github.com/vitejs/vite/pull/16471) جایی که API جدید پیاده‌سازی و بررسی شده است.

لطفاً نظرات و بازخوردهای خود را با ما به اشتراک بگذارید.
:::

## استانداردسازی محیط‌ها

Vite 6 مفهوم محیط‌ها را استانداردسازی می‌کند. تا نسخه‌ی Vite 5، دو محیط پیش‌فرض وجود داشت: (`client` و در صورت نیاز `ssr`). Environment API (رابط برنامه‌نویسی محیط) جدید به کاربران و توسعه‌دهندگان فریمورک‌ها اجازه می‌دهد تا به تعداد مورد نیاز محیط ایجاد کنند و آن را با نحوه‌ی عملکرد برنامه‌هایشان در محیط پروداکشن تطبیق دهند. این قابلیت جدید نیازمند بازنگری گسترده‌ای در ساختار داخلی بود، اما تلاش زیادی برای حفظ سازگاری با نسخه‌های قبلی صورت گرفته است. هدف اولیه‌ی Vite 6 این است که اکوسیستم را به‌آرامی به نسخه‌ی جدید منتقل کند و پذیرش این APIهای آزمایشی جدید را تا زمانی که تعداد کافی از کاربران مهاجرت کرده و توسعه‌دهندگانِ فریمورک‌ها و افزونه‌ها طراحی جدید را تأیید کنند، به تعویق بیندازد.

## کاهش فاصله بین ساخت و توسعه

برای یک SPA/MPA ساده، هیچ API جدیدی در مورد محیط‌ها به پیکربندی افزوده نشده است. از نظر داخلی، Vite گزینه‌ها را به محیط `client` اعمال خواهد کرد، اما نیازی به دانستن این مفهوم هنگام پیکربندی Vite نیست. پیکربندی و رفتار موجود در Vite 5 باید به‌طور یکپارچه در اینجا کار کند.

هنگامی که به سمت یک اپلیکیشن معمولی رندر شده در سمت سرور (SSR) می‌رویم، دو محیط خواهیم داشت:

* `client`: اپلیکیشن را در مرورگر اجرا می‌کند.
* `ssr`: اپلیکیشن را در Node (یا سایر رانتایم‌ها سرور) اجرا می‌کند که صفحات را قبل از ارسال به مرورگر رندر می‌کند.

در محیط توسعه (dev)، Vite کد سرور را در همان فرآیند Node که سرور توسعه Vite را اجرا می‌کند، اجرا می‌کند، که شبیه‌سازی نزدیکی به محیط پروداکشن ایجاد می‌کند. با این حال، ممکن است سرورها در رانتایم جاوااسکریپت دیگری مانند [Workerd Cloudflare](https://github.com/cloudflare/workerd) اجرا شوند که محدودیت‌های متفاوتی دارند. اپلیکیشن‌های مدرن همچنین ممکن است در بیشتر از دو محیط اجرا شوند، مثلاً یک مرورگر، یک سرور Node و یک سرور لبه. Vite 5 قادر به نمایاندن مناسب این محیط‌ها نبود.

Vite 6 به کاربران امکان می‌دهد برنامه خود را طوری پیکربندی کنند که همه محیط‌های اجرایی آن را در فرایند توسعه و ساخت پوشش دهد. در زمان توسعه، اکنون یک سرور توسعه Vite می‌تواند همزمان کد را در چندین محیط مختلف اجرا کند. سورس کد برنامه همچنان توسط سرور توسعه Vite تبدیل می‌شود. علاوه بر سرور HTTP مشترک، میان‌افزارها، تنظیمات پردازش‌شده و زنجیره پلاگین‌ها، سرور توسعه Vite اکنون دارای مجموعه‌ای از محیط‌های توسعه مستقل است. هر محیط توسعه طوری پیکربندی شده که تا حد امکان به محیط پروداکشن شبیه باشد و به یک رانتایم توسعه متصل است که کد در آن اجرا می‌شود (برای مثال در مورد Workerd، کد سرور اکنون می‌تواند به صورت محلی در Miniflare اجرا شود). در سمت کلاینت، مرورگر کد را ایمپورت و اجرا می‌کند، و در سایر محیط‌ها، یک اجراکننده ماژول، کد تبدیل‌شده را بارگیری و ارزیابی می‌کند.

![Vite Environments](../images/vite-environments.svg)

## پیکربندی محیط‌ها

برای یک برنامه SPA/MPA، پیکربندی مشابه Vite 5 خواهد بود. به صورت داخلی، این گزینه‌ها برای پیکربندی محیط `client` استفاده می‌شوند.

```js
export default defineConfig({
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
})
```

این مهم است زیرا ما می‌خواهیم Vite را قابل دسترس نگه داریم و از معرفی مفاهیم جدید تا زمانی که واقعاً به آنها نیاز نباشد، خودداری کنیم.

اگر برنامه از چندین محیط تشکیل شده باشد، این محیط‌ها می‌توانند به صورت صریح با گزینه پیکربندی `environments` تنظیم شوند.

```js
export default {
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
  environments: {
    server: {},
    edge: {
      resolve: {
        noExternal: true,
      },
    },
  },
}
```

اگر به صورت صریح مستند نشده باشد، هر محیط از گزینه‌های پیکربندی سطح بالا ارث می‌برد (به عنوان مثال، محیط‌های جدید `server` و `edge` گزینه `build.sourcemap: false` را به ارث می‌برند). تعداد کمی از گزینه‌های سطح بالا، مانند `optimizeDeps`، فقط برای محیط `client` اعمال می‌شوند، زیرا زمانی که به عنوان پیش‌فرض به محیط‌های سرور اعمال می‌شوند، به خوبی کار نمی‌کنند. محیط `client` همچنین می‌تواند به صورت صریح از طریق `environments.client` پیکربندی شود، اما توصیه می‌کنیم این کار را با گزینه‌های سطح بالا انجام دهید تا پیکربندی کلاینت هنگام اضافه کردن محیط‌های جدید بدون تغییر باقی بماند.

رابط `EnvironmentOptions` تمام گزینه‌های مختص هر محیط را در اختیار قرار می‌دهد. برخی گزینه‌های محیطی هم برای `build` و هم برای `dev` اعمال می‌شوند، مانند `resolve`. همچنین `DevEnvironmentOptions` و `BuildEnvironmentOptions` برای گزینه‌های خاص توسعه و ساخت وجود دارند (مانند `dev.warmup` یا `build.outDir`). برخی گزینه‌ها مانند `optimizeDeps` فقط برای توسعه اعمال می‌شوند، اما برای حفظ سازگاری با نسخه‌های قبلی، به جای قرار گرفتن در `dev`، در سطح بالا نگه داشته شده‌اند.

```ts
interface EnvironmentOptions {
  define?: Record<string, any>
  resolve?: EnvironmentResolveOptions
  optimizeDeps: DepOptimizationOptions
  consumer?: 'client' | 'server'
  dev: DevOptions
  build: BuildOptions
}
```

رابط `UserConfig` از رابط `EnvironmentOptions` گسترش می‌یابد، که امکان پیکربندی کلاینت و پیش‌فرض‌ها را برای سایر محیط‌ها، از طریق گزینه `environments` فراهم می‌کند. محیط `client` و یک محیط سرور با نام `ssr` همیشه در زمان توسعه حاضر هستند. این امر باعث سازگاری با نسخه‌های قبلی برای `server.ssrLoadModule(url)` و `server.moduleGraph` می‌شود. در زمان بیلد، محیط `client` همیشه وجود دارد، و محیط `ssr` تنها در صورتی وجود خواهد داشت که به صورت صریح پیکربندی شده باشد (با استفاده از `environments.ssr` یا برای سازگاری با نسخه‌های قبلی `build.ssr`). یک برنامه لزوماً نیازی به استفاده از نام `ssr` برای محیط SSR خود ندارد، می‌تواند آن را به عنوان مثال `server` نام‌گذاری کند.

```ts
interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // other options
}
```

توجه داشته باشید که ویژگی سطح بالای `ssr` پس از پایدار شدن API محیط، منسوخ خواهد شد. این گزینه نقشی مشابه با `environments` دارد، اما فقط برای محیط پیش‌فرض `ssr` است و تنها امکان پیکربندی مجموعه کوچکی از گزینه‌ها را فراهم می‌کند.

## نمونه‌های محیط سفارشی

APIهای پیکربندی سطح پایین در دسترس هستند تا ارائه‌دهندگان رانتایم بتوانند محیط‌هایی با پیش‌فرض‌های مناسب برای رانتایم خود فراهم کنند. این محیط‌ها همچنین می‌توانند فرآیندها یا نخ‌های دیگری را برای اجرای ماژول‌ها در زمان توسعه در یک رانتایم نزدیک‌تر به محیط تولید ایجاد کنند.

```js
import { customEnvironment } from 'vite-environment-provider'

export default {
  build: {
    outDir: '/dist/client',
  },
  environments: {
    ssr: customEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
  },
}
```

## سازگاری با نسخه‌های قبلی

APIهای سرور فعلی Vite هنوز منسوخ نشده‌اند و با Vite 5 سازگار هستند. API محیط جدید در حالت آزمایشی است.

متد `server.moduleGraph` یک نمای ترکیبی از گراف‌های ماژول‌های کلاینت و SSR را باز می‌گرداند. نودهای ماژول ترکیبی که سازگاری با نسخه‌های قبلی دارند، از تمام متدهای این آبجکت باز می‌گردند. همین الگو برای نودهای ماژول‌هایی که به متد `handleHotUpdate` ارسال می‌شوند نیز استفاده می‌شود. به عبارت دیگر، این ویژگی به شما اجازه می‌دهد که هم ماژول‌های مرتبط با کلاینت و هم ماژول‌های مرتبط با SSR را به‌طور همزمان مدیریت کنید و نودهای مربوط به هرکدام را به‌طور یکپارچه در دسترس داشته باشید.

ما هنوز توصیه نمی‌کنیم که به API محیط تغییر دهید. هدف ما این است که بخش زیادی از کاربران قبل از این تغییرات، Vite 6 را پذیرفته و استفاده کنند تا پلاگین‌ها نیازی به نگهداری دو نسخه مختلف نداشته باشند. برای اطلاعات بیشتر در مورد تغییرات مخرب آینده و مسیر ارتقا، به بخش تغییرات مخرب آینده مراجعه کنید:

* [`this.environment` در Hooks](/changes/this-environment-in-hooks)
* [HMR `hotUpdate` Plugin Hook](/changes/hotupdate-hook)
* [انتقال به API‌های مخصوص هر محیط](/changes/per-environment-apis)
* [SSR با استفاده از `ModuleRunner` API](/changes/ssr-using-modulerunner)
* [پلاگین‌های مشترک در طول فرآیند ساخت](/changes/shared-plugins-during-build)

## کاربران هدف

این راهنما مفاهیم پایه‌ای درباره محیط‌ها را برای کاربران نهایی ارائه می‌دهد.

نویسندگان پلاگین‌ها یک API سازگارتر برای تعامل با پیکربندی محیط فعلی دارند. اگر شما بر روی Vite توسعه می‌دهید، راهنمای [API پلاگین‌های محیط](./api-environment-plugins.md) روش استفاده از API‌های اضافی پلاگین‌ها را توضیح می‌دهد که از محیط‌های سفارشی متعدد پشتیبانی می‌کنند.

فریم‌ورک‌ها می‌توانند تصمیم بگیرند که محیط‌ها را در سطوح مختلفی در دسترس قرار دهند. اگر شما نویسنده یک فریم‌ورک هستید، برای آشنایی با بخش برنامه‌نویسی API محیط، ادامه مطلب را در [راهنمای API محیط برای فریم‌ورک‌ها](./api-environment-frameworks) مطالعه کنید.

برای ارائه‌دهندگان رانتایم (Runtime providers)، [راهنمای API محیط برای رانتایم](./api-environment-runtimes.md) توضیح می‌دهد که چگونه می‌توان یک محیط سفارشی را برای استفاده توسط فریم‌ورک‌ها و کاربران ارائه داد.