前言

由于對vite的喜愛，所以本人首次嘗試英文文檔的翻譯，由于本人英文水平有限。如果有哪里翻譯錯誤或是無法get到原文的準確意思請指出會及時修正。為了更好的閱讀體驗強烈推薦跳轉到下方地址進行閱讀。

https://github.com/zhangyuang/vite-design?github.comhttps://vite-design.surge.sh/guide/chinese-doc.html?vite-design.surge.sh

vite ?

Vite 是一個有態度的 web 開發構建工具，在本地開發時使用原生的 ES Module 特性導入你的代碼。在生產環境使用 Rollup 打包代碼。

• 更快的冷啟動速度
• 即時的熱替換功能
• 真正的按需編譯
• 更多詳細信息請查看How and Why

狀態

目前在beta階段, 預計很快發布1.0版本。

快速開始

對于 Vue 用戶來說: Vite 目前僅支持 Vue 3.x. 這意味著你不能使用尚未與 Vue 3 兼容的庫$ npm init vite-app <project-name> $ cd <project-name> $ npm install $ npm run dev

如果你使用yarn:

$ yarn create vite-app <project-name> $ cd <project-name> $ yarn $ yarn dev雖然 Vite 主要是為了與 Vue 3 一起工作而設計的, 但它同時也能很好的支持其他框架。例如, 你可以嘗試 npm init vite-app --template react 或者 --template preact.

使用 master 分支

如果你迫不及待的想要測試最新的特性，克隆 vite 到本地并且執行以下命令:

yarn yarn build yarn link

然后進入基于 vite 創建的項目并且執行 yarn link vite。 現在可以重啟你的服務 (yarn dev) 去體驗最新的特性！

Browser Support

Vite 在開發環境下依賴原生ES module imports。在生產環境構建時依賴動態加載實現代碼分割 (polyfill參考polyfilled)

Vite 假設你的代碼運行在現代瀏覽器上，默認將會使用 es2019 規范來轉換你的代碼。(這使得可選鏈功能在代碼壓縮后能被使用)。同時你能夠手動的在配置選項中指定構建目標版本。最低的版本規范是 es2015。

功能

• Bare Module Resolving
• Hot Module Replacement
• TypeScript
• CSS / JSON Importing
• Asset URL Handling
• PostCSS
• CSS Modules
• CSS Pre-processors
• JSX
• Web Assembly
• Inline Web Workers
• Custom Blocks
• Config File
• HTTPS/2
• Dev Server Proxy
• Production Build
• Modes and Environment Variables

Vite 盡可能的嘗試復用 vue-cli 的默認配置。如果你之前使用過 vue-cli 或者其他基于 Webpack 的模版項目，你應該會非常熟悉這些。這意味著不要期望在這里和那里會有什么不同。

Bare Module Resolving

原生的 ES imports 規范不支持裸模塊的導入，例如

import { createApp } from 'vue'

這種寫法默認將會拋出錯誤。Vite 會檢測到當前服務中的所有 .js 文件，并且重寫他們的路徑例如 /@modules/vue。 在這種路徑下，Vite 將會從你安裝的依賴中正確的解析執行模塊。

對于 vue 這個依賴則有著特殊的處理。如果你沒有在項目的本地依賴中安裝，Vite 將會回退到它自身的依賴版本。這意味著如果你全局安裝了 Vite, 它將更快的找到 Vue 實例而不需要在本地安裝依賴。

Hot Module Replacement

• vue react 以及 preact 模版已經在 create-vite-app 集成了熱替換功能可以開箱即用
• 為了手動的控制熱替換功能, 可以使用該 API import.meta.hot.

如果模塊想要接收到自身替換回調, 可以使用 import.meta.hot.accept:

```js

export const count = 1

// 這個條件判斷使得熱替換相關的代碼將會在生產環境被丟棄

if (import.meta.hot) { import.meta.hot.accept((newModule) => { console.log('updated: count is now ', newModule.count) }) } ```

一個模塊同樣能夠接收到來自其他模塊的更新通知而不需要重新加載。可以使用 import.meta.hot.acceptDeps：

```js

import { foo } from './foo.js'

foo()

if (import.meta.hot) { import.meta.hot.acceptDeps('./foo.js', (newFoo) => { // 回調函數將會在 './foo.js' 被更新時觸發 newFoo.foo() })

// 同樣我們可以接受一個數組 import.meta.hot.acceptDeps(['./foo.js', './bar.js'], ([newFooModule, newBarModule]) => {// 回調函數將會在這個數組中的模塊被更新時觸發 })

}

```

接收自身更新通知的模塊或者接收來自其他模塊更新通知的模塊可以使用 hot.dispose 來清理一些更新過程中產生的副作用

```js

function setupSideEffect() {}

setupSideEffect()

if (import.meta.hot) { import.meta.hot.dispose((data) => { // cleanup side effect }) }

```

完整的API可以查看 hmr.d.ts.

Vite 的熱替換功能并不會交換導入的模塊來源。如果一個被接收的模塊被重復的導出了，它有責任去更新這些重復的導出(這些導出必須使用 let)。另外，接收模塊的上游將不會被通知這些變化。(這塊嘗試寫了一些事例驗證但是還是無法get到原文想表達的準確意思)

這個簡潔的的熱替換實現在很多開發場景是足夠用的。這使得我們可以跳過昂貴的生成代理模塊的過程。

TypeScript

Vite 支持在Vue 單文件組件中使用 <script lang="ts"> 導入 .ts 文件。

Vite 只進行 .ts 文件的轉換而不會進行類型檢查。它假設類型檢查已經在你的 IDE 或者在構建命令中已經被加入進來了(例如你可以在構建腳本中執行 tsc --noEmit)。

Vite 使用 esbuild 來轉換 TypeScript 到 JavaScript 速度相比 tsc 快 20-30倍。 熱替換的更新時間在瀏覽器中將小于50ms。

因為 esbuild 僅進行轉換不附帶類型信息。所以它不支持以下功能例如常量枚舉以及隱式的類型導入。你必須在 tsconfig.json 文件的 compilerOptions 選項中設置 "isolatedModules": true, 這樣 TS 將會警告你這些功能在這個選項下不能被使用。

CSS / JSON Importing

You can directly import .css and .json files from JavaScript (including <script> tags of *.vue files, of course).

• .json 文件的內容將會以默認導出的形式導出一個對象
• .css 文件將不會導出任何東西除非它是以 .module.css 作為后綴名。(查看 CSS Modules)。 在開發環境下導入它會產生副作用并且注入到頁面當中，在生產環境最終會單獨打包為 style.css 文件。

CSS 和 JSON 的導入都支持熱替換功能。

Asset URL Handling

你可以在 *.vue 模版 styles 標簽以及 .css 文件中引用靜態資源，通過絕對的靜態目錄路徑(基于你的項目根目錄) 或者相對路徑 (基于當前文件)。后者的行為與你之前在 vue-cli 或者webpack的 file-loader 的使用方式非常像。

所有被引用的資源包括使用絕對路徑引用的資源最終都會被復制到打包后的 dist 文件夾當中并且文件名包含 has h值, 沒有被引用的文件將不會被復制。與 vue-cli 一樣，小于 4kb 的圖片資源將會以 base64 的形式內聯。

所有的靜態資源路徑引用，包括絕對路徑都是基于你當前的工作目錄結構。

The public Directory

項目工程下的 public 目錄提供不會在源碼中引入靜態文件資源文件(例如 robots.txt), 或者必須保留原始名稱的文件(不附帶 hash 值)。

public 目錄中的文件將會被復制到最終的 dist 文件夾當中。

如果要引用 public 中的文件需要使用絕對路徑，例如 public/icon.png 文件在源碼中的引用方式為 /icon.png。

Public Base Path

如果你的項目以嵌套文件夾的形式發布?？梢允褂?--base=/your/public/path/ 選項，這樣所有的靜態資源的路徑會被自動重寫。

為了動態的路徑引用，這里有兩種方式提供

• 你可以獲得解析后的靜態文件路徑通過在 JavaScript 中 導入不它們。例如 import path from './foo.png' 將會以字符串的形式返回加載路徑。
• 如果你需要在云端拼接完整的路徑，可以使用注入的全局變量 import.meta.env.BASE_URL 它的值等于靜態資源的基路徑。這個變量在構建過程中是靜態的，所以它必須以這種方式出現。 (import.meta.env['BASE_URL'] 將不會生效)

PostCSS

Vite 將自動的在 *.vue 文件中的所有 styles 標簽 以及所有導入的 .css 文件中應用 PostCSS。只需要安裝必要的插件并且在項目根目錄下添加 postcss.config.js 配置文件。

CSS Modules

如果你想使用 CSS Modules 你并不需要配置 PostCSS，因為這已經集成好是開箱即用的。在 *.vue 組件中你可以使用 <stype module>, 在 .css 文件中你可以使用 *.module.css 的后綴名便可以以帶有 hash 值的形式來導入它們。

CSS Pre-Processors

因為 Vite 期望你的代碼將會運行在現代瀏覽器中，所以它建議使用原生的 CSS 變量結合 PostCSS 插件來實現 CSSWG 草案 (例如 postcss-nesting) 使其變得簡潔以及標準化。這意味著，如果你堅持要使用 CSS 預處理，你需要在本地安裝預處理器然后使用。

yarn add -D sass <style lang="scss"> /* use scss */ </style>

同樣也可以在 JS 文件中導入

import './style.scss'

Passing Options to Pre-Processor

要求版本大于等于 1.0.0-beta.9+ 如果你需要修改默認預處理器的配置，你可以使用 config 文件中的 cssPreprocessOptions 選項(查看 Config File) 例如為你的 less 文件定義一個全局變量// vite.config.js module.exports = {cssPreprocessOptions: {less: {modifyVars: {'preprocess-custom-color': 'green'}}} }

JSX

.jsx and .tsx files are also supported. JSX transpilation is also handled via esbuild.

.jsx 以及 .tsx files 同樣是支持的。 JSX 文件同樣使用 esbuild 來進行轉換。

默認與 Vue3 結合的 JSX 配置是開箱即用的 (對 Vue 來說目前還沒有針對 JSX 語法的熱替換功能)

import { createApp } from 'vue'function App() {return <Child>{() => 'bar'}</Child> }function Child(_, { slots }) {return <div onClick={() => console.log('hello')}>{slots.default()}</div> }createApp(App).mount('#app')

同時這種寫法將會自動導入與 jsx 兼容的函數，esbuild 將會轉換 JSX 使其成為與 Vue 3 兼容并且能夠在虛擬節點中被調用。Vue 3 最終將提供可利用Vue 3的運行時快速的自定義JSX轉換。

JSX with React/Preact

我們準備了兩種方案分別是 react 和 preact。你可以使用 Vite 執行下列命令來進行方案的選擇使用 --jsx react or --jsx preact。

如果你需要一個自定義的 JSX 編譯規則，JSX 支持自定義通過在 CLI 中使用 --jsx-factory 以及 --jsx-fragment 標志?；蛘呤褂?API 提供的 jsx: { factory, fragment }。例如你可執行 vite --jsx-factory=h 來使用 h 作為 JSX 元素被創建時候的函數調用。在配置文件中 (參考 Config File), 可以通過下面的寫法來指定。

// vite.config.js module.exports = {jsx: {factory: 'h',fragment: 'Fragment'} }

在使用 Preact 作為預置的場景下， h 已經自動注入在上下文當中，不需要手動的導入。然而這會導致在使用 .tsx 結合 Preact 的情況下 TS 為了類型推斷期望 h 函數能夠被顯示的導入。在這種情況下，你可以顯示的指定 factory 配置來禁止 h 函數的自動注入。

Web Assembly

1.0.0-beta.3+

預編譯的 .wasm 文件能夠被直接導入。默認的導出會作為初始化函數返回一個 Promise 對象來導出 wasm 實例對象:

import init from './example.wasm'init().then(exports => {exports.test() })

init 函數也能夠獲取到 imports 對象作為 WebAssembly.instantiate 的第二個參數傳遞。

init({imports: {someFunc: () => { /* ... */ }} }).then(() => { /* ... */ })

在生產環境構建時，小于 assetInlineLimit 大小限制的 .wasm 文件將會以 base64 的形式內聯。否則將會復制到 dist 文件夾作為靜態資源被獲取。

Inline Web Workers

1.0.0-beta.3+

web worker 腳本能夠被直接導入只需要在后面加上 ?workder。默認的導出是一個自定義的 workder 構造函數。

import MyWorker from './worker?worker'const worker = new MyWorker()

在生產環境構建時，workders 將會以 base64 的形式內聯。

worker 腳本同樣使用 import 而不是 importScripts()，在開發環境下這依賴于瀏覽器的原生支持，并且僅在 Chrome 中能夠工作，但是生產環境已經被編譯過了。

如果你不希望內聯 worker 腳本，你可以替換你的 workder 腳本到 public 文件夾，然后初始化 workder 例如 new Worker('/worker.js')

Config File

你可以在當前項目中創建一個 vite.config.js 或者 vite.config.ts 文件。Vite 將會自動的使用它。你也可以通過 vite --config my-config.js 顯式的指定配置文件。

除了在 CLI 映射的選項之外，它也支持 alias, transfroms, plugins (將作為配置接口的子集)選項。在文檔完善之前參考 config.ts 來獲得更全面的信息。

Custom Blocks

自定義區塊 在 Vue 的單文件組件中也是支持的。可以通過 vueCustomBlockTransforms 選項來指定自定義區塊的轉換規則:

// vite.config.js module.exports = {vueCustomBlockTransforms: {i18n: ({ code }) => {// return transformed code}} }

HTTPS/2

通過 --https 的方式來啟動服務將會自動生成自簽名的證書。并且服務將會啟用 TLS 以及 HTTP/2。

同樣可以通過 httpsOptions 選項來自定義簽名證書。與 Node 的 https.ServerOptions 一樣支持接收以下參數 key, cert, ca, pfx。

Dev Server Proxy

你可以使用配置文件中的 proxy 選項來自定義本地開發服務的代理功能。Vite 使用 koa-proxies](https://github.com/vagusX/koa-proxies), 它底層使用了http-proxy。鍵名可以是一個路徑，更多的配置可以查看 here。

用例:

// vite.config.js module.exports = {proxy: {// string shorthand'/foo': 'http://localhost:4567/foo',// with options'/api': {target: 'http://jsonplaceholder.typicode.com',changeOrigin: true,rewrite: path => path.replace(/^/api/, '')}} }

Production Build

Vite 在生產環境構建時會進行打包。因為原生的 ES 模塊導入在瀑布流網絡請求中很容易導致頁面的加載時間過長讓人難以接受。

執行 vite build 來打包應用。

在內部我們使用 Rollup 來生成最終的構建結果。構建配置我們將會透傳給 Rollup，一些選項我們可以通過 CLI 來進行透傳 (參考 build/index.ts 來獲得更多信息)。

Modes and Environment Variables

模式選項用于指定 import.meta.env.MODE 的值，同時正確的環境變量文件將會被加載。

默認存在兩種模式: - development 使用于 vite 以及 vite serve - production 使用于 vite build

你可以通過 --mode 選項來覆蓋默認的模式，例如你想以開發模式來進行構建：

vite build --mode development

當執行 vite 命令時，環境變量將會從當前目錄的以下文件中被加載

.env # 在任何情況下都被加載 .env.local # 在任何情況下都被加載, 會被 git 忽略 .env.[mode] # 僅在當前指定的模式下被加載 .env.[mode].local # 僅在當前指定的模式下被加載, 會被 git 忽略

只有 VITE_ 開頭的變量會暴露在你的代碼中。例如 VITE_SOME_KEY=123 將會暴露在 import.meta.env.VITE_SOME_KEY。但是 SOME_KEY=123 將不會。 因為 .env 文件或許會被一些用戶在服務端或者構建腳本中使用。有可能包含一些敏感信息不適合出現在瀏覽器。

API

Dev Server

你可以使用這個 API 來自定義本地開發服務。這個服務接受一些插件并且將會注入到 Koa app 實例當中：

const { createServer } = require('vite')const myPlugin = ({root, // 項目根路徑，絕對路徑app, // Koa app 實例server, // http server 實例watcher // chokidar file watcher instance }) => {app.use(async (ctx, next) => {// 你可以在這里做一些預處理。這些是最原始的請求// 在 vite 接觸它之前if (ctx.path.endsWith('.scss')) {// vue <style lang="xxx"> 默認已經被支持只要默認的預處理器被安裝// 所以下面的寫法僅應用于 <link ref="stylesheet" href="*.scss"> 或者 js imports like// `import '*.scss'`.console.log('pre processing: ', ctx.url)ctx.type = 'css'ctx.body = 'body { border: 1px solid red }'}// ...wait for vite to do built-in transformsawait next()// Post processing before the content is served. Note this includes parts// compiled from `*.vue` files, where <template> and <script> are served as// `application/javascript` and <style> are served as `text/css`.// 在內容被發送之前進行預處理包括以下部分// 編譯 `*.vue` 文件，<template> 和 <script> 以 `application/javascript` 的形式托管服務， <style> 以 `text/css` 的形式托管服務if (ctx.response.is('js')) {console.log('post processing: ', ctx.url)console.log(ctx.body) // 可以是字符串或者可讀流}}) }createServer({configureServer: [myPlugin] }).listen(3000)

Build

獲取更全面的選項請查看 build/index.ts

const { build } = require('vite');(async () => {// All options are optional.// check out `src/node/build/index.ts` for full options interface.const result = await build({rollupInputOptions: {// https://rollupjs.org/guide/en/#big-list-of-options},rollupOutputOptions: {// https://rollupjs.org/guide/en/#big-list-of-options},rollupPluginVueOptions: {// https://github.com/vuejs/rollup-plugin-vue/tree/next#options}// ...}) })()

How and Why

與 vue-cli 以及 其他打包工具的區別

主要的區別是 Vite 在開發環境下沒有打包的過程。源碼中的模塊的導入語法是服務端直接發送給瀏覽器運行。瀏覽器解析它們通過原生的 <script module> 支持，對每一個 import 使用 http 請求。本地開發服務將攔截這些請求并進行必要的代碼轉換。例如 import *.vue 文件將會在發送給瀏覽器之前被編譯。

通過這種方式處理我們有以下優勢:

• 不需要等待打包，所以冷啟動的速度將會非常快
• 代碼是按需編譯的。只有你當前頁面實際導入的模塊才會被編譯。你不需要等待整個應用程序被打包完才能夠啟動服務。這在有很多頁面的應用上體驗差別更加巨大。
• 熱替換的性能將與模塊的總數量無關。這將使得熱替換變得非常迅速無論你的應用有多大。

整個頁面的刷新比起基于工具打包會慢一點。存在很深的導入鏈的情況下的原生的 ES 模塊的導入很容易導致網絡瀑布。然而這是本地開發與實際編譯相比差別應該不大。(在頁面重載時不需要編譯，因為編譯結果已經緩存在內存中了)

因為編譯是在 Node 中完成的，在技術上我們可以進行任何的代碼轉換，沒有什么可以阻止你捆綁最終打包到生產環境的代碼。事實上， Vite 提供了 vite build 命令來進行精確的打包讓你的應用在生產環境中不會發生網絡瀑布。

How is This Different from es-dev-server?

es-dev-server 是一個非常好的項目，我們早期設計有很多靈感來自于它。下面是 Vite 和 es-dev-server 的區別以及為什么我們不以 es-dev-server 中間件的形式來實現 Vite：

• Vite 的主要目標之一是實現熱替換，但是 es-dev-server 的內部不是很透明導致無法通過中間件來使其很好的工作
• Vite 目標做一個獨立的工作同時在開發環境以及構建時使用。你可以無需配置便可以針對同一份源碼在開發環境或構建時使用 Vite
• Vite 對處理一些明確類型的導入文件是更加有態度的。例如 .css 文件和靜態資源?；谏鲜隼碛蛇@些處理方式類似于 vue-cli

How is This Different from Snowpack?

Snowpack v2 和 Vite 在本地開發服務都提供了原生 ES 模塊的導入。Vite 依賴預優化的靈感也來自于Snowpack v1。在開發反饋速度上面，兩個項目非常類似。一些值得注意的不同點如下：

• Vite 被創造出來用于處理基于原生 ES 模塊的熱替換功能。當 Vite 首次發布能夠正常工作的基于原生 ES 模塊的熱替換功能時，沒有其他的項目積極嘗試將原生 ES 模塊的熱替換功能用于生產。

Snowpack v2 最初也不支持熱替換但是計劃在之后的版本提供。這將使得兩個項目更加的類似。Vite 和 Snowpack 計劃合作針對原生 ES 模塊的熱替換提供一個通用的 API 規范。但是由于兩個項目的內部實現方式的區別，兩個項目的 API 仍將會有所區別。

• 兩個項目的解決方案都是在生產環境進行應用的打包。但是 Vite 使用 Rollup 進行構建，Snowpack 通過插件使用 Parcel/webpack 進行構建。Vite 在很多場景下構建結果是更快并且更小的。另外與打包程序更緊密的結合可以更容易的在開發環境和生產環境配置中修改 Vite 的轉換規則以及插件。
• Vue support is a first-class feature in Vite. For example, Vite provides a much more fine-grained HMR integration with Vue, and the build config is fined tuned to produce the most efficient bundle.
• Vite 對 Vue 的支持是一流的。Vite 針對 Vue 提供了更細粒度的熱替換功能以及在構建配置上做了調整來生成最有效的打包結果。

Contribution

See Contributing Guide.

Trivia

vite is the french word for "fast" and is pronounced /vit/.

License

MIT

總結

以上是生活随笔為你收集整理的wtl单文档选项_Vite 中文文档翻译的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。