release: v2.5.1

Author: QC-L

config/index.md

@@ -415,7 +415,7 @@ export default defineConfig(async ({ command, mode }) => {
           changeOrigin: true,
           configure: (proxy, options) => {
             // proxy 是 'http-proxy' 的实例
-          },
+          }
         }
       }
     }
@@ -530,7 +530,7 @@ createServer()
 
 ### build.target {#build-target}
 
-- **类型：** `string`
+- **类型：** `string | string[]`
 - **默认：** `'modules'`
 - **相关内容：:** [浏览器兼容性](/guide/build#browser-compatibility)
 
@@ -647,12 +647,6 @@ createServer()
 
   传递给 Terser 的更多 [minify 选项](https://terser.org/docs/api-reference#minify-options)。
 
-### build.cleanCssOptions {#build-cleancssoptions}
-
-- **类型：** `CleanCSS.Options`
-
-  传递给 [clean-css](https://github.com/jakubpawlowicz/clean-css#constructor-options) 的构造器选项。
-
 ### build.write {#build-write}
 
 - **类型：** `boolean`
@@ -741,9 +735,9 @@ SSR 选项可能会在未来版本中进行调整。
 
 ### ssr.noExternal {#ssr-noexternal}
 
-- **类型：** `string | RegExp | (string | RegExp)[]`
+- **类型：** `string | RegExp | (string | RegExp)[] | true`
 
-  列出的是防止被 SSR 外部化依赖项。
+  列出的是防止被 SSR 外部化依赖项。如果设为 `true`，将没有依赖被外部化。
 
 ### ssr.target
 

guide/dep-pre-bundling.md

@@ -38,6 +38,11 @@ Pre-bundling them to speed up dev server page load...（将预构建它们以提
 
 在一个 monorepo 启动中，该仓库中的某个依赖可能会成为另一个包的依赖。Vite 会自动侦测没有从 `node_modules` 解析的依赖项，并将链接的依赖视为源码。它不会尝试打包被链接的依赖，而是会分析被链接依赖的依赖列表。
 
+::: warning Note
+由于依赖关系的处理方式不同，链接的依赖关系在最终构建时可能无法正常工作。
+使用 `npm package` 代替所有本地依赖，以避免最终的 bundle 问题。
+:::
+
 ## 自定义行为 {#customizing-the-behavior}
 
 默认的依赖项发现为启发式可能并不总是可取的。在你想要显式地从列表中包含/排除依赖项的情况下, 请使用 [`optimizeDeps` 配置项](/config/#dep-optimization-options)。

guide/features.md

@@ -34,7 +34,37 @@ Vite 仅执行 `.ts` 文件的转译工作，并 **不** 执行任何类型检
 
 Vite 使用 [esbuild](https://github.com/evanw/esbuild) 将 TypeScript 转译到 JavaScript，约是 `tsc` 速度的 20~30 倍，同时 HMR 更新反映到浏览器的时间小于 50ms。
 
-注意因为 `esbuild` 只执行转译工作而不含类型信息，所以它不支持 TypeScript 的特定功能例如常量枚举和隐式 “type-only” 导入。你必须在你的 `tsconfig.json` 中的 `compilerOptions` 里设置 `"isolatedModules": true`，这样 TS 才会警告你哪些功能无法与独立编译模式一同工作。
+### TypeScript 编译器选项 {#typescript-compiler-options}
+
+`tsconfig.json` 中 `compilerOptions` 下的一些配置项需要特别注意。
+
+#### `isolatedModules`
+
+应该设置为 `true`。
+
+这是因为 `esbuild` 只执行没有类型信息的转译，它并不支持某些特性，如 `const enum` 和隐式类型导入。
+
+你必须在 `tsconfig.json` 中的 `compilerOptions` 下设置 `"isolatedModules": true`。如此做，TS 会警告你不要使用隔离（isolated）转译的功能。
+
+#### `useDefineForClassFields`
+
+从 Vite v2.5.0 开始，如果 TypeScript 的 target 是 `ESNext`，此选项默认值则为 `true`。这与 [`tsc` v4.3.2 及以后版本的行为](https://github.com/microsoft/TypeScript/pull/42663) 一致。这也是标准的 ECMAScript 的运行时行为。
+
+但对于那些习惯其他编程语言或旧版本 TypeScript 的开发者来说，这可能是违反直觉的。
+你可以参阅 [TypeScript 3.7 发布日志](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier) 中了解更多关于如何兼容的信息。
+
+如果你正在使用一个严重依赖 class fields 的库，请注意该库对此选项的预期设置。
+
+大多数库都希望 `"useDefineForClassFields": true`，如 [MobX](https://mobx.js.org/installation.html#use-spec-compliant-transpilation-for-class-properties)，[Vue Class Components 8.x](https://github.com/vuejs/vue-class-component/issues/465) 等。
+
+但是有几个库还没有兼容这个新的默认值，其中包括 [`lit-element`](https://github.com/lit/lit-element/issues/1030)。如果遇到这种情况，请将 `useDefineForClassFields` 设置为 `false`。
+
+#### 影响构建结果的其他编译器选项 {#other-compiler-options-affecting-the-build-result}
+
+- [`extends`](https://www.typescriptlang.org/tsconfig#extends)
+- [`importsNotUsedAsValues`](https://www.typescriptlang.org/tsconfig#importsNotUsedAsValues)
+- [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
+- [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
 
 ### 客户端类型 {#client-types}
 

guide/ssr.md

@@ -248,6 +248,13 @@ export function mySSRPlugin() {
 }
 ```
 
-## SSR Target
+## SSR Target {#ssr-target}
 
 SSR 构建的默认目标为 node 环境，但你也可以让服务运行在 Web Worker 上。每个平台的打包条目解析是不同的。你可以将`ssr.target` 设置为 `webworker`，以将目标配置为 Web Worker。
+
+## SSR Bundle {#ssr-bundle}
+
+在某些如 `webworker` 运行时等特殊情况中，你可能想要将你的 SSR 打包成单个 JavaScript 文件。你可以通过设置 `ssr.noExternal` 为 `true` 来启用这个行为。这将会做两件事：
+
+- 将所有依赖视为 `noExternal`（非外部化）
+- 若任何 Node.js 内置内容被引入，将抛出一个错误

guide/static-deploy.md

@@ -10,7 +10,7 @@
 {
   "scripts": {
     "build": "vite build",
-    "preview": "vite preview"
+    "serve": "vite preview"
   }
 }
 ```
@@ -33,21 +33,21 @@ $ npm run build
 
 ### 本地测试应用 {#testing-the-app-locally}
 
-当你构建完成应用后，你可以通过运行 `npm run preview` 命令，在本地测试该应用。
+当你构建完成应用后，你可以通过运行 `npm run serve` 命令，在本地测试该应用。
 
 ```bash
 $ npm run build
-$ npm run preview
+$ npm run serve
 ```
 
-`preview` 命令会在本地启动一个静态 Web 服务器，将 `dist` 文件夹运行在 http://localhost:5000。这样在本地环境下查看该构建产物是否正常可用就方便了。
+`vite preview` 命令会在本地启动一个静态 Web 服务器，将 `dist` 文件夹运行在 http://localhost:5000。这样在本地环境下查看该构建产物是否正常可用就方便了。
 
 你可以通过 `--port` 参数来配置服务的运行端口。
 
 ```json
 {
   "scripts": {
-    "preview": "vite preview --port 8080"
+    "serve": "vite preview --port 8080"
   }
 }
 ```
@@ -56,6 +56,10 @@ $ npm run preview
 
 ## GitHub Pages {#github-pages}
 
+::: tip 注意
+如果你将 script 的名字 `serve` 改为了 `preview`，你可能会遇到某些包管理工具在处理 [前置 & 后置 scripts](https://docs.npmjs.com/cli/v7/using-npm/scripts#pre--post-scripts) 方面的问题。
+:::
+
 1. 在 `vite.config.js` 中设置正确的 `base`。
 
    如果你要部署在 `https://<USERNAME>.github.io/` 上，你可以省略 `base` 使其默认为 `'/'`。