release: v2.5.7

Author: ShenQingchuan

config/index.md

@@ -206,6 +206,14 @@ export default defineConfig(async ({ command, mode }) => {
 
   导入时想要省略的扩展名列表。注意，**不** 建议忽略自定义导入类型的扩展名（例如：`.vue`），因为它会影响 IDE 和类型支持。
 
+### resolve.preserveSymlinks {#resolve-preservesymlinks}
+
+- **类型：** `boolean`
+- **默认：** `false`
+
+  启用此选项会使 Vite 通过原始文件路径（即不跟随符号链接的路径）而不是真正的文件路径（即跟随符号链接后的路径）确定文件身份。
+
+- **相关：** [esbuild#preserve-symlinks](https://esbuild.github.io/api/#preserve-symlinks)，[webpack#resolve.symlinks](https://webpack.js.org/configuration/resolve/#resolvesymlinks)
 ### css.modules {#css-modules}
 
 - **类型：**
@@ -333,6 +341,18 @@ export default defineConfig(async ({ command, mode }) => {
 
   关于环境文件的更多信息，请参见 [这里](/guide/env-and-mode#env-files)。
 
+### envPrefix
+
+- **类型：** `string | string[]`
+- **默认：** `VITE_`
+
+  以 `envPrefix` 开头的环境变量会通过 import.meta.env 暴露在你的客户端源码中。
+
+:::warning 安全注意事项
+
+- `envPrefix` 不应该被设置为 `''`，因为这将暴露你所有的环境变量，导致敏感信息的意外泄露。Vite 在检测到 `''` 时将会抛出错误。
+  :::
+  
 ## 开发服务器选项 {#server-options}
 
 ### server.host {#server-host}
@@ -475,7 +495,7 @@ const { createServer: createViteServer } = require('vite')
 async function createServer() {
   const app = express()
 
-  // 以中间件模式创建 vite 服务器
+  // 以中间件模式创建 Vite 服务器
   const vite = await createViteServer({
     server: { middlewareMode: 'ssr' }
   })
@@ -692,7 +712,7 @@ createServer()
 
   默认情况下，Vite 会抓取你的 index.html 来检测需要预构建的依赖项。如果指定了 `build.rollupOptions.input`，Vite 将转而去抓取这些入口点。
 
-  如果这两者都不合你意，则可以使用此选项指定自定义条目——该值需要遵循 [fast-glob 模式](https://github.com/mrmlnc/fast-glob#basic-syntax) ，或者是相对于 vite 项目根的模式数组。这将覆盖掉默认条目推断。
+  如果这两者都不合你意，则可以使用此选项指定自定义条目——该值需要遵循 [fast-glob 模式](https://github.com/mrmlnc/fast-glob#basic-syntax) ，或者是相对于 Vite 项目根的模式数组。这将覆盖掉默认条目推断。
 
 ### optimizeDeps.exclude {#optimizedeps-exclude}
 
@@ -701,7 +721,16 @@ createServer()
   在预构建中强制排除的依赖项。
 
   :::warning CommonJS
-  CommonJS 的依赖不应该排除在优化外。如果一个 ESM 依赖拥有一个嵌套的 CommonJS 依赖，它也不应被排除。
+  CommonJS 的依赖不应该排除在优化外。如果一个 ESM 依赖被排除在优化外，但是却有一个嵌套的 CommonJS 依赖，则应该为该 CommonJS 依赖添加 `optimizeDeps.include`。例如：
+
+  ```js
+  export default defineConfig({
+    optimizeDeps: {
+      include: ['esm-dep > cjs-dep']
+    }
+  })
+  ```
+
   :::
 
 ### optimizeDeps.include {#optimizedeps-include}

guide/api-javascript.md

@@ -40,7 +40,7 @@ const { createServer } = require('vite')
 ```ts
 interface ViteDevServer {
   /**
-   * 被解析的 vite 配置对象
+   * 被解析的 Vite 配置对象
    */
   config: ResolvedConfig
   /**
@@ -82,7 +82,7 @@ interface ViteDevServer {
     options?: TransformOptions
   ): Promise<TransformResult | null>
   /**
-   * 应用 vite 内建 HTML 转换和任意插件 HTML 转换
+   * 应用 Vite 内建 HTML 转换和任意插件 HTML 转换
    */
   transformIndexHtml(url: string, html: string): Promise<string>
   /**

guide/api-plugin.md

@@ -414,6 +414,15 @@ function myPlugin() {
 }
 ```
 
+同时，还可以使用函数来进行更精准的控制：
+
+```js
+apply(config, { command }) {
+  // 非 SSR 情况下的 build
+  return command === 'build' && !config.build.ssr
+}
+```
+
 ## Rollup 插件兼容性 {#rollup-plugin-compatibility}
 
 相当数量的 Rollup 插件将直接作为 Vite 插件工作（例如：`@rollup/plugin-alias` 或 `@rollup/plugin-json`），但并不是所有的，因为有些插件钩子在非构建式的开发服务器上下文中没有意义。

guide/build.md

@@ -4,7 +4,7 @@
 
 ## 浏览器兼容性 {#browser-compatibility}
 
-用于生产环境的构建包会假设目标浏览器支持现代 JavaScript 语法。默认情况下，vite 的目标浏览器是指能够 [支持原生 ESM script 标签](https://caniuse.com/es6-module) 和 [支持原生 ESM 动态导入](https://caniuse.com/es6-module-dynamic-import) 的。作为参考，vite 使用这个 [browserslist](https://github.com/browserslist/browserslist) 作为查询标准：
+用于生产环境的构建包会假设目标浏览器支持现代 JavaScript 语法。默认情况下，Vite 的目标浏览器是指能够 [支持原生 ESM script 标签](https://caniuse.com/es6-module) 和 [支持原生 ESM 动态导入](https://caniuse.com/es6-module-dynamic-import) 的。作为参考，Vite 使用这个 [browserslist](https://github.com/browserslist/browserslist) 作为查询标准：
 
 ```
 defaults and supports es6-module and supports es6-module-dynamic-import, not opera > 0, not samsung > 0, not and_qq > 0

guide/env-and-mode.md

@@ -16,7 +16,7 @@ Vite 在一个特殊的 **`import.meta.env`** 对象上暴露环境变量。这
 
 在生产环境中，这些环境变量会在构建时被**静态替换**，因此，在引用它们时请使用完全静态的字符串。动态的 key 将无法生效。例如，动态 key 取值 `import.meta.env[key]` 是无效的。
 
-它还将替换出现在 JavaScript 和 Vue 模板中的字符串。这应该是一种罕见的情况，但可能是不小心为之的。有一些方法可以避免这个问题：
+它还将替换出现在 JavaScript 和 Vue 模板中的字符串。这本应是非常少见的，但也可能是不小心为之的。在这种情况下你可能会看到类似 `Missing Semicolon` 或 `Unexpected token` 等错误，例如当 `"process.env.NODE_ENV"` 被替换为 `""development": "`。有一些方法可以避免这个问题：
 
 - 对于 JavaScript 字符串，你可以使用 unicode 零宽度空格 **`\u200b`** (一个看不见的分隔符)来分割这个字符串，例如： `'import.meta\u200b.env.MODE'`。
 
@@ -44,6 +44,8 @@ VITE_SOME_KEY=123
 
 只有 `VITE_SOME_KEY` 会被暴露为 `import.meta.env.VITE_SOME_KEY` 提供给客户端源码，而 `DB_PASSWORD` 则不会。
 
+如果你想自定义 env 变量的前缀，请参阅 [envPrefix](/config/index#envprefix)。
+
 :::warning 安全注意事项
 
 - `.env.*.local` 文件应是本地的，可以包含敏感变量。你应该将 `.local` 添加到你的 `.gitignore` 中，以避免它们被 git 检入。

guide/index.md

@@ -37,7 +37,7 @@ $ yarn create vite
 使用 PNPM:
 
 ```bash
-$ pnpx create-vite
+$ pnpm dlx create-vite
 ```
 
 然后按照提示操作即可！
@@ -133,7 +133,7 @@ yarn build
 yarn link
 ```
 
-然后，回到你的 vite 项目并运行 `yarn link vite`。重新启动开发服务器（`yarn dev`）来体验新功能吧！
+然后，回到你的 Vite 项目并运行 `yarn link vite`。重新启动开发服务器（`yarn dev`）来体验新功能吧！
 
 ## 社区 {#community}
 

guide/ssr.md

@@ -73,7 +73,7 @@ const { createServer: createViteServer } = require('vite')
 async function createServer() {
   const app = express()
 
-  // 以中间件模式创建 vite 应用，这将禁用 Vite 自身的 HTML 服务逻辑
+  // 以中间件模式创建 Vite 应用，这将禁用 Vite 自身的 HTML 服务逻辑
   // 并让上级服务器接管控制
   //
   // 如果你想使用 Vite 自己的 HTML 服务逻辑（将 Vite 作为
@@ -109,7 +109,7 @@ app.use('*', async (req, res) => {
       'utf-8'
     )
 
-    // 2. 应用 vite HTML 转换。这将会注入 vite HMR 客户端，
+    // 2. 应用 Vite HTML 转换。这将会注入 Vite HMR 客户端，
     //    同时也会从 Vite 插件应用 HTML 转换。
     //    例如：@vitejs/plugin-react-refresh 中的 global preambles
     template = await vite.transformIndexHtml(url, template)
@@ -130,7 +130,7 @@ app.use('*', async (req, res) => {
     // 6. 返回渲染后的 HTML。
     res.status(200).set({ 'Content-Type': 'text/html' }).end(html)
   } catch (e) {
-    // 如果捕获到了一个错误，让 vite 来修复该堆栈，这样它就可以映射回
+    // 如果捕获到了一个错误，让 Vite 来修复该堆栈，这样它就可以映射回
     // 你的实际源码中。
     vite.ssrFixStacktrace(e)
     console.error(e)