release: v2.7.13

config/index.md

@@ -23,6 +23,14 @@ export default {
 vite --config my-config.js
 ```
 
+注意，Vite 会替换 `__filename`，`__dirname` 以及 `import.meta.url`。如果使用这些名称作为变量名可能会导致代码报错：
+
+```js
+const __filename = "value"
+// will be transformed to
+const "path/vite.config.js" = "value"
+```
+
 ### 配置智能提示 {#config-intellisense}
 
 因为 Vite 本身附带 Typescript 类型，所以你可以通过 IDE 和 jsdoc 的配合来实现智能提示：
@@ -131,9 +139,21 @@ export default defineConfig(async ({ command, mode }) => {
 
   例如，`process.env.FOO` 和 `__APP_VERSION__` 就非常适合。但 `process` 或 `global` 不应使用此选项。变量相关应使用 shim 或 polyfill 代替。
 
+  ::: tip NOTE
+  对于使用 TypeScript 的开发者来说，请确保在 `env.d.ts` 或 `vite-env.d.ts` 文件中添加类型声明，以获得类型检查以及代码提示。
+
+  Example:
+
+  ```ts
+  // vite-env.d.ts
+  declare const __APP_VERSION__: string
+  ```
+
+  :::
+
 ### plugins {#plugins}
 
-- **类型：** ` (Plugin | Plugin[])[]`
+- **类型：** `(Plugin | Plugin[])[]`
 
   需要用到的插件数组。Falsy 虚值的插件将被忽略，插件数组将被扁平化（flatten）。查看 [插件 API](/guide/api-plugin) 获取 Vite 插件的更多细节。
 
@@ -153,14 +173,14 @@ export default defineConfig(async ({ command, mode }) => {
 - **类型：** `string`
 - **默认：** `"node_modules/.vite"`
 
-  存储缓存文件的目录。此目录下会存储预打包的依赖项或 vite 生成的某些缓存文件，使用缓存可以提高性能。如需重新生成缓存文件，你可以使用 `--force` 命令行选项或手动删除目录。此选项的值可以是文件的绝对路径，也可以是以项目根目录为基准的相对路径。
+  存储缓存文件的目录。此目录下会存储预打包的依赖项或 vite 生成的某些缓存文件，使用缓存可以提高性能。如需重新生成缓存文件，你可以使用 `--force` 命令行选项或手动删除目录。此选项的值可以是文件的绝对路径，也可以是以项目根目录为基准的相对路径。当没有检测到 package.json 时，则默认为 `.vite`。
 
 ### resolve.alias {#resolve-alias}
 
 - **类型：**
-  `Record<string, string> | Array<{ find: string | RegExp, replacement: string }>`
+  `Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>`
 
-  将会被传递到 `@rollup/plugin-alias` 作为 [entries 的选项](https://github.com/rollup/plugins/tree/master/packages/alias#entries)。也可以是一个对象，或一个 `{ find, replacement }` 的数组。
+  将会被传递到 `@rollup/plugin-alias` 作为 [entries 的选项](https://github.com/rollup/plugins/tree/master/packages/alias#entries)。也可以是一个对象，或一个 `{ find, replacement, customResolver }` 的数组。
 
   当使用文件系统路径的别名时，请始终使用绝对路径。相对路径的别名值会原封不动地被使用，因此无法被正常解析。
 
@@ -770,6 +790,8 @@ export default defineConfig({
 
   设置为 `false` 可以禁用最小化混淆，或是用来指定使用哪种混淆器。默认为 [Esbuild](https://github.com/evanw/esbuild)，它比 terser 快 20-40 倍，压缩率只差 1%-2%。[Benchmarks](https://github.com/privatenumber/minification-benchmarks)
 
+  注意，在 lib 模式下使用 `'es'` 时，`build.minify` 选项将失效。
+
 ### build.terserOptions {#build-terseroptions}
 
 - **类型：** `TerserOptions`
@@ -826,7 +848,7 @@ export default defineConfig({
 ### preview.port {#preview-port}
 
 - **类型：** `number`
-- **默认：** `5000`
+- **默认：** `4173`
 
   指定开发服务器端口。注意，如果设置的端口已被使用，Vite 将自动尝试下一个可用端口，所以这可能不是最终监听的服务器端口。
 
@@ -957,3 +979,24 @@ SSR 选项可能会在未来版本中进行调整。
 - **默认：** `node`
 
   SSR 服务器的构建目标。
+
+## Worker 选项 {#worker-options}
+
+### worker.format
+
+- **类型：** `'es' | 'iife'`
+- **默认：** `iife`
+
+  worker bundle 的输出类型。
+
+### worker.plugins
+
+- **类型：** [`(Plugin | Plugin[])[]`](#plugins)
+
+  适用于 worker bundle 的 Vite 插件。
+
+### worker.rollupOptions
+
+- **类型：** [`RollupOptions`](https://rollupjs.org/guide/en/#big-list-of-options)
+
+  用于构建 worker bundle 的 Rollup 配置项。

guide/env-and-mode.md

@@ -33,6 +33,15 @@ Vite 使用 [dotenv](https://github.com/motdotla/dotenv) 从你的 [环境目录
 .env.[mode].local   # 只在指定模式下加载，但会被 git 忽略
 ```
 
+:::tip 环境加载优先级
+
+一份用于指定模式的文件（例如 `.env.production`）会比通用形式的优先级更高（例如 `.env`）。
+
+另外，Vite 执行时已经存在的环境变量有最高的优先级，不会被 `.env` 类文件覆盖。
+
+`.env` 类文件会在 Vite 启动一开始时被加载，而改动会在重启服务器后生效。
+:::
+
 加载的环境变量也会通过 `import.meta.env` 暴露给客户端源码。
 
 为了防止意外地将一些环境变量泄漏到客户端，只有以 `VITE_` 为前缀的变量才会暴露给经过 vite 处理的代码。例如下面这个文件中：

guide/features.md

@@ -34,6 +34,13 @@ Vite 仅执行 `.ts` 文件的转译工作，并 **不** 执行任何类型检
 
 Vite 使用 [esbuild](https://github.com/evanw/esbuild) 将 TypeScript 转译到 JavaScript，约是 `tsc` 速度的 20~30 倍，同时 HMR 更新反映到浏览器的时间小于 50ms。
 
+使用 [仅含类型的导入和导出](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export) 形式的语法可以避免潜在的 “仅含类型的导入被不正确打包” 的问题，写法示例如下：
+
+```ts
+import type { T } from 'only/types'
+export type { T }
+```
+
 ### TypeScript 编译器选项 {#typescript-compiler-options}
 
 `tsconfig.json` 中 `compilerOptions` 下的一些配置项需要特别注意。
@@ -63,6 +70,7 @@ Vite 使用 [esbuild](https://github.com/evanw/esbuild) 将 TypeScript 转译到
 
 - [`extends`](https://www.typescriptlang.org/tsconfig#extends)
 - [`importsNotUsedAsValues`](https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues)
+- [`preserveValueImports`](https://www.typescriptlang.org/tsconfig#preserveValueImports)
 - [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
 - [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
 
@@ -183,13 +191,13 @@ document.getElementById('foo').className = applyColor
 
 ```bash
 # .scss and .sass
-npm install -D sass
+npm add -D sass
 
 # .less
-npm install -D less
+npm add -D less
 
 # .styl and .stylus
-npm install -D stylus
+npm add -D stylus
 ```
 
 如果是用的是单文件组件，可以通过 `<style lang="sass">`（或其他预处理器）自动开启。

guide/index.md

@@ -38,13 +38,13 @@ Vite 意在提供开箱即用的配置，同时它的 [插件 API](./api-plugin)
 ## 搭建第一个 Vite 项目 {#scaffolding-your-first-vite-project}
 
 ::: tip 兼容性注意
-Vite 需要 [Node.js](https://nodejs.org/en/) 版本 >= 12.0.0。
+Vite 需要 [Node.js](https://nodejs.org/en/) 版本 >= 12.0.0。然而，有些模板需要依赖更高的 Node 版本才能正常运行，当你的包管理器发出警告时，请注意升级你的 Node 版本。
 :::
 
 使用 NPM:
 
 ```bash
-$ npm init vite@latest
+$ npm create vite@latest
 ```
 
 使用 Yarn:
@@ -65,10 +65,10 @@ $ pnpm create vite
 
 ```bash
 # npm 6.x
-npm init vite@latest my-vue-app --template vue
+npm create vite@latest my-vue-app --template vue
 
-# npm 7+, 需要额外的双横线：
-npm init vite@latest my-vue-app -- --template vue
+# npm 7+, extra double-dash is needed:
+npm create vite@latest my-vue-app -- --template vue
 
 # yarn
 yarn create vite my-vue-app --template vue

guide/using-plugins.md

@@ -7,7 +7,7 @@ Vite 可以使用插件进行扩展，这得益于 Rollup 优秀的插件接口
 若要使用一个插件，需要将它添加到项目的 `devDependencies` 并在 `vite.config.js` 配置文件中的 `plugins` 数组中引入它。例如，要想为传统浏览器提供支持，可以按下面这样使用官方插件 [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy)：
 
 ```
-$ npm i -D @vitejs/plugin-legacy
+$ npm add -D @vitejs/plugin-legacy
 ```
 
 ```js