docs(cn): update with main stream

release v4.2.1

Author: waynzh

.vitepress/config.ts

@@ -38,6 +38,7 @@ export default defineConfig({
     en: { label: 'English', link: 'https://vitejs.dev' },
     ja: { label: '日本語', link: 'https://ja.vitejs.dev' },
     es: { label: 'Español', link: 'https://es.vitejs.dev' },
+    pt: { label: 'Português', link: 'https://pt.vitejs.dev' },
   },
 
   vue: {

_data/team.js

@@ -66,7 +66,7 @@ export const core = [
     title: 'Developer',
     org: 'Vue.js',
     orgLink: 'https://vuejs.org/',
-    desc: 'Vite/Vite core team member. Full-time open sourcerer.',
+    desc: 'Vue/Vite core team member. Full-time open sourcerer.',
     links: [
       { icon: 'github', link: 'https://github.com/sodatea' },
       { icon: 'twitter', link: 'https://twitter.com/haoqunjiang' },

blog/announcing-vite2.md

@@ -4,6 +4,8 @@ sidebar: false
 
 # Vite 2.0 发布了 {#announcing-vite-2-0}
 
+_February 16, 2021_ - Check out the [Vite 3.0 announcement](./announcing-vite3.md)
+
 <p style="text-align:center">
   <img src="/logo.svg" style="height:200px">
 </p>

blog/announcing-vite3.md

@@ -23,6 +23,8 @@ head:
 
 # Vite 3.0 is out!
 
+_July 23, 2022_ - Check out the [Vite 4.0 announcement](./announcing-vite4.md)
+
 In February last year, [Evan You](https://twitter.com/youyuxi) released Vite 2. Since then, its adoption has grown non-stop, reaching more than 1 million npm downloads per week. A sprawling ecosystem rapidly formed after the release. Vite is powering a renewed innovation race in Web frameworks. [Nuxt 3](https://v3.nuxtjs.org/) uses Vite by default. [SvelteKit](https://kit.svelte.dev/), [Astro](https://astro.build/), [Hydrogen](https://hydrogen.shopify.dev/), and [SolidStart](https://docs.solidjs.com/start) are all built with Vite. [Laravel has now decided to use Vite by default](https://laravel.com/docs/9.x/vite). [Vite Ruby](https://vite-ruby.netlify.app/) shows how Vite can improve Rails DX. [Vitest](https://vitest.dev) is making strides as a Vite-native alternative to Jest. Vite is behind [Cypress](https://docs.cypress.io/guides/component-testing/writing-your-first-component-test) and [Playwright](https://playwright.dev/docs/test-components)'s new Component Testing features, Storybook has [Vite as an official builder](https://github.com/storybookjs/builder-vite). And [the list goes on](https://patak.dev/vite/ecosystem.html). Maintainers from most of these projects got involved in improving the Vite core itself, working closely with the Vite [team](https://vitejs.dev/team) and other contributors.
 
 ![Vite 3 Announcement Cover Image](/og-image-announcing-vite3.png)

blog/announcing-vite4.md

@@ -23,6 +23,8 @@ head:
 
 # Vite 4.0 is out!
 
+_December 9, 2022_
+
 Vite 3 [was released](./announcing-vite3.md) five months ago. npm downloads per week have gone from 1 million to 2.5 million since then. The ecosystem has matured too, and continues to grow. In this year's [Jamstack Conf survey](https://twitter.com/vite_js/status/1589665610119585793), usage among the community jumped from 14% to 32% while keeping a high 9.7 satisfaction score. We saw the stable releases of [Astro 1.0](https://astro.build/), [Nuxt 3](https://v3.nuxtjs.org/), and other Vite-powered frameworks that are innovating and collaborating: [SvelteKit](https://kit.svelte.dev/), [Solid Start](https://www.solidjs.com/blog/introducing-solidstart), [Qwik City](https://qwik.builder.io/qwikcity/overview/). Storybook announced first-class support for Vite as one of its main features for [Storybook 7.0](https://storybook.js.org/blog/first-class-vite-support-in-storybook/). Deno now [supports Vite](https://www.youtube.com/watch?v=Zjojo9wdvmY). [Vitest](https://vitest.dev) adoption is exploding, it will soon represent half of Vite's npm downloads. Nx is also investing in the ecosystem, and [officially supports Vite](https://nx.dev/packages/vite).
 
 [![Vite 4 Ecosystem](/ecosystem-vite4.png)](https://viteconf.org/2022/replay)

config/build-options.md

@@ -10,7 +10,7 @@
 
 另一个特殊值是 “esnext” —— 即假设有原生动态导入支持，并且将会转译得尽可能小：
 
-- 如果 [`build.minify`](#build-minify) 选项为 `'terser'`，`'esnext'` 将会强制降级为 `'es2021'`。
+- 如果 [`build.minify`](#build-minify) 选项为 `'terser'`，并且安装的 Terser 版本小于 5.16.0，`'esnext'` 将会强制降级为 `'es2021'`。
 - 其他情况下将完全不会执行转译。
 
 转换过程将会由 esbuild 执行，并且此值应该是一个合法的 [esbuild 目标选项](https://esbuild.github.io/api/#target)。自定义目标也可以是一个 ES 版本（例如：`es2015`）、一个浏览器版本（例如：`chrome58`）或是多个目标组成的一个数组。
@@ -78,7 +78,7 @@ modulePreload: {
 - **类型：** `string`
 - **默认：** `assets`
 
-指定生成静态资源的存放路径（相对于 `build.outDir`）。
+指定生成静态资源的存放路径（相对于 `build.outDir`）。在 [库模式](/guide/build#library-mode) 下不能使用。
 
 ## build.assetsInlineLimit {#build-assetsinlinelimit}
 
@@ -106,7 +106,7 @@ Git LFS 占位符会自动排除在内联之外，因为它们不包含它们所
 如果指定了 `build.lib`，`build.cssCodeSplit` 会默认为 `false`。
 :::
 
-## build.cssTarget
+## build.cssTarget {#build-csstarget}
 
 - **类型：** `string | string[]`
 - **默认值：** 与 [`build.target`](/config/#build-target) 一致
@@ -117,6 +117,13 @@ Git LFS 占位符会自动排除在内联之外，因为它们不包含它们所
 最直观的示例是当你要兼容的场景是安卓微信中的 webview 时，它支持大多数现代的 JavaScript 功能，但并不支持 [CSS 中的 `#RGBA` 十六进制颜色符号](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#rgb_colors)。
 这种情况下，你需要将 `build.cssTarget` 设置为 `chrome61`，以防止 vite 将 `rgba()` 颜色转化为 `#RGBA` 十六进制符号的形式。
 
+## build.cssMinify {#build-cssminify}
+
+- **类型：** `boolean`
+- **默认：** 与 [`build.minify`](#build-minify) 一致
+
+此选项允许用户覆盖 CSS 最小化压缩的配置，而不是使用默认的 `build.minify`，这样你就可以单独配置 JS 和 CSS 的最小化压缩方式。Vite 使用 `esbuild` 来最小化 CSS。
+
 ## build.sourcemap {#build-sourcemap}
 
 - **类型：** `boolean | 'inline' | 'hidden'`
@@ -229,7 +236,7 @@ npm add -D terser
 - **类型：** `number`
 - **默认：** `500`
 
-规定触发警告的 chunk 大小。（以 kbs 为单位）
+规定触发警告的 chunk 大小。（以 kbs 为单位）。它将与未压缩的 chunk 大小进行比较，因为 [JavaScript 大小本身与执行时间相关](https://v8.dev/blog/cost-of-javascript-2019)。
 
 ## build.watch {#build-watch}
 

config/dep-optimization-options.md

@@ -51,3 +51,17 @@ export default defineConfig({
 - **类型：** `boolean`
 
 设置为 `true` 可以强制依赖预构建，而忽略之前已经缓存过的、已经优化过的依赖。
+
+## optimizeDeps.disabled {#optimizedeps-disabled}
+
+- **实验性**
+- **类型：** `boolean | 'build' | 'dev'`
+- **默认：** `'build'`
+
+禁用依赖优化，值为 `true` 将在构建和开发期间均禁用优化器。传 `'build'` 或 `'dev'` 将仅在其中一种模式下禁用优化器。默认情况下，仅在开发阶段启用依赖优化。
+
+:::warning
+在构建模式下依赖优化是 **实验性** 的。如果开启此项，那么它将消除开发与构建最终产物之间的最明显的区别之一。[`@rollup/plugin-commonjs`](https://github.com/rollup/plugins/tree/master/packages/commonjs) 在此处将不再需要，因为 esbuild 会将纯 CJS 依赖转换为 ESM。
+
+如果你想尝试该构建策略，你可以使用 `optimizeDeps.disabled: false`。`@rollup/plugin-commonjs` 可以通过设置 `build.commonjsOptions: { include: [] }` 来移除。
+:::

config/server-options.md

@@ -312,7 +312,7 @@ export default defineConfig({
 
 - **类型：** `string`
 
-用于定义开发调试阶段生成资产的 origin。
+用于定义开发调试阶段生成资源的 origin。
 
 ```js
 export default defineConfig({
@@ -321,3 +321,30 @@ export default defineConfig({
   },
 })
 ```
+
+## server.sourcemapIgnoreList {#server-sourcemapignorelist}
+
+- **类型：** `false | (sourcePath: string, sourcemapPath: string) => boolean`
+- **默认：** `(sourcePath) => sourcePath.includes('node_modules')`
+
+是否忽略服务器 sourcemap 中的源文件，用于填充 [`x_google_ignoreList` source map 扩展](https://developer.chrome.com/blog/devtools-better-angular-debugging/#the-x_google_ignorelist-source-map-extension)。
+
+对开发服务器来说 `server.sourcemapIgnoreList` 等价于 [`build.rollupOptions.output.sourcemapIgnoreList`](https://rollupjs.org/configuration-options/#output-sourcemapignorelist)。两个配置选项之间的区别在于，rollup 函数使用相对路径调用 `sourcePath`，而 `server.sourcemapIgnoreList` 使用绝对路径调用。在开发过程中，大多数模块的映射和源文件位于同一个文件夹中，因此 `sourcePath` 的相对路径就是文件名本身。在这些情况下，使用绝对路径更加方便。
+
+默认情况下，它会排除所有包含 `node_modules` 的路径。你可以传递 `false` 来禁用此行为，或者为了获得完全的控制，可以传递一个函数，该函数接受源路径和 sourcemap 的路径，并返回是否忽略源路径。
+
+```js
+export default defineConfig({
+  server: {
+    // 这是默认值，它将把所有路径中含有 node_modules 的文件
+    // 添加到忽略列表中。
+    sourcemapIgnoreList(sourcePath, sourcemapPath) {
+      return sourcePath.includes('node_modules')
+    }
+  }
+};
+```
+
+::: tip 注意
+需要单独设置 [`server.sourcemapIgnoreList`](#server-sourcemapignorelist) 和 [`build.rollupOptions.output.sourcemapIgnoreList`](https://rollupjs.org/configuration-options/#output-sourcemapignorelist)。`server.sourcemapIgnoreList` 是一个仅适用于服务端的配置，并不从定义好的 rollup 选项中获得其默认值。
+:::

config/shared-options.md

@@ -188,7 +188,6 @@ Vite 有一个“允许的情景”列表，并且会匹配列表中第一个情
 ## css.modules {#css-modules}
 
 - **类型：**
-
 ```ts
 interface CSSModulesOptions {
   scopeBehaviour?: 'global' | 'local'
@@ -227,7 +226,15 @@ interface CSSModulesOptions {
 
 - **类型：** `Record<string, object>`
 
-指定传递给 CSS 预处理器的选项。文件扩展名用作选项的键，例如：
+指定传递给 CSS 预处理器的选项。文件扩展名用作选项的键。每个预处理器支持的选项可以在它们各自的文档中找到：
+
+- `sass`/`scss` - [选项](https://sass-lang.com/documentation/js-api/interfaces/LegacyStringOptions)。
+- `less` - [选项](https://lesscss.org/usage/#less-options)。
+- `styl`/`stylus` - 仅支持 [`define`](https://stylus-lang.com/docs/js.html#define-name-node)，可以作为对象传递。
+
+所有预处理器选项还支持 `additionalData` 选项，可以用于为每个样式内容注入额外代码。
+
+示例：
 
 ```js
 export default defineConfig({
@@ -236,8 +243,13 @@ export default defineConfig({
       scss: {
         additionalData: `$injectedColor: orange;`,
       },
+      less: {
+        math: 'parens-division',
+      },
       styl: {
-        additionalData: `$injectedColor ?= orange`,
+        define: {
+          $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1),
+        },
       },
     },
   },
@@ -326,6 +338,40 @@ export default defineConfig({
 
 调整控制台输出的级别，默认为 `'info'`。
 
+## customLogger {#customlogger}
+
+- **类型：**
+  ```ts
+  interface Logger {
+    info(msg: string, options?: LogOptions): void
+    warn(msg: string, options?: LogOptions): void
+    warnOnce(msg: string, options?: LogOptions): void
+    error(msg: string, options?: LogErrorOptions): void
+    clearScreen(type: LogType): void
+    hasErrorLogged(error: Error | RollupError): boolean
+    hasWarned: boolean
+  }
+  ```
+
+使用自定义 logger 记录消息。可以使用 Vite 的 `createLogger` API 获取默认的 logger 并对其进行自定义，例如，更改消息或过滤掉某些警告。
+
+```js
+import { createLogger, defineConfig } from 'vite'
+
+const logger = createLogger()
+const loggerWarn = logger.warn
+
+logger.warn = (msg, options) => {
+  // 忽略空 CSS 文件的警告
+  if (msg.includes('vite:css') && msg.includes(' is empty')) return
+  loggerWarn(msg, options)
+}
+
+export default defineConfig({
+  customLogger: logger,
+})
+```
+
 ## clearScreen {#clearscreen}
 
 - **类型：** `boolean`
@@ -351,6 +397,15 @@ export default defineConfig({
 
 :::warning 安全注意事项
 `envPrefix` 不应被设置为空字符串 `''`，这将暴露你所有的环境变量，导致敏感信息的意外泄漏。 检测到配置为 `''` 时 Vite 将会抛出错误.
+
+如果你想暴露一个不含前缀的变量，可以使用 [define](#define) 选项：
+
+```js
+define: {
+  'import.meta.env.ENV_VARIABLE': JSON.stringify(process.env.ENV_VARIABLE)
+}
+```
+
 :::
 
 ## appType {#apptype}

config/worker-options.md

@@ -5,7 +5,7 @@
 ## worker.format
 
 - **类型：** `'es' | 'iife'`
-- **默认：** `iife`
+- **默认：** `'iife'`
 
 worker 打包时的输出类型。
 

guide/api-hmr.md

@@ -51,6 +51,13 @@ if (import.meta.hot) {
 }
 ```
 
+## TypeScript 的智能提示 {#intellisense-for-typescript}
+Vite 在 [`vite/client.d.ts`](https://github.com/vitejs/vite/blob/main/packages/vite/client.d.ts) 中为 `import.meta.hot` 提供了类型定义。你可以在 `src` 目录中创建一个 `env.d.ts`，以便 TypeScript 获取类型定义：
+
+```ts
+/// <reference types="vite/client" />
+```
+
 ## `hot.accept(cb)` {#hot-accept-cb}
 
 要接收模块自身，应使用 `import.meta.hot.accept`，参数为接收已更新模块的回调函数：

guide/api-javascript.md

@@ -34,7 +34,7 @@ const __dirname = fileURLToPath(new URL('.', import.meta.url))
 ```
 
 ::: tip 注意
-当在同一个 Node.js 进程中使用 `createServer` 和 `build` 时，两个函数都依赖于 `process.env.`<wbr>`NODE_ENV` 才可正常工作，而这个环境变量又依赖于 `mode` 配置项。为了避免行为冲突，请在这两个 API 传入参数 `development` 字段中设置 `process.env.`<wbr>`NODE_ENV` 或者 `mode` 配置项，或者你也可以生成另一个子进程，分别运行这两个 API。
+当在同一个 Node.js 进程中使用 `createServer` 和 `build` 时，两个函数都依赖于 `process.env.NODE_ENV` 才可正常工作，而这个环境变量又依赖于 `mode` 配置项。为了避免行为冲突，请在这两个 API 传入参数 `development` 字段中设置 `process.env.NODE_ENV` 或者 `mode` 配置项，或者你也可以生成另一个子进程，分别运行这两个 API。
 :::
 
 ## `InlineConfig` {#inlineconfig}

guide/api-plugin.md

@@ -159,6 +159,8 @@ console.log(msg)
 - [`load`](https://rollupjs.org/plugin-development/#load)
 - [`transform`](https://rollupjs.org/plugin-development/#transform)
 
+它们还有一个扩展的 `options` 参数，包含其他特定于 Vite 的属性。你可以在 [SSR 文档](/guide/ssr#ssr-specific-plugin-logic) 中查阅更多内容。
+
 以下钩子在服务器关闭时被调用：
 
 - [`buildEnd`](https://rollupjs.org/plugin-development/#buildend)
@@ -478,7 +480,7 @@ apply(config, { command }) {
 
 一般来说，只要 Rollup 插件符合以下标准，它就应该像 Vite 插件一样工作：
 
-- 没有使用 [`moduleParsed`](https://rollupjs.org/guide/en/#moduleparsed) 钩子。
+- 没有使用 [`moduleParsed`](https://rollupjs.org/plugin-development/#moduleparsed) 钩子。
 - 它在打包钩子和输出钩子之间没有很强的耦合。
 
 如果一个 Rollup 插件只在构建阶段有意义，则在 `build.rollupOptions.plugins` 下指定即可。它的工作原理与 Vite 插件的 `enforce: 'post'` 和 `apply: 'build'` 相同。
@@ -535,7 +537,10 @@ export default defineConfig({
     {
       // ...
       configureServer(server) {
-        server.ws.send('my:greetings', { msg: 'hello' })
+        // 示例：等待客户端连接后再发送消息
+        server.ws.on('connection', () => {
+          server.ws.send('my:greetings', { msg: 'hello' })
+        })
       },
     },
   ],

guide/build.md

@@ -211,7 +211,7 @@ dist/my-lib.umd.cjs 0.30 KiB / gzip: 0.16 KiB
 :::
 
 ::: tip 环境变量
-在库模式下，所有 `import.meta.env.*` 用法在构建生产时都会被静态替换。但是，`process.env.*` 的用法不会被替换，所以你的库的使用者可以动态地更改它。如果不想允许他们这样做，你可以使用 `define: { 'process.env.`<wbr>`NODE_ENV': '"production"' }` 例如静态替换它们。
+在库模式下，所有 `import.meta.env.*` 用法在构建生产时都会被静态替换。但是，`process.env.*` 的用法不会被替换，所以你的库的使用者可以动态地更改它。如果不想允许他们这样做，你可以使用 `define: { 'process.env.NODE_ENV': '"production"' }` 例如静态替换它们。
 :::
 
 ## 进阶基础路径选项 {#advanced-base-options}

guide/cli.md

@@ -54,7 +54,7 @@ vite build [root]
 | `--assetsDir <dir>`            | 在输出目录下放置资源的目录（默认为：`"assets"`）(`string`) |
 | `--assetsInlineLimit <number>` | 静态资源内联为 base64 编码的阈值，以字节为单位（默认为：`4096`）(`number`) |
 | `--ssr [entry]`                | 为服务端渲染配置指定入口文件 (`string`) |
-| `--sourcemap`                  | 构建后输出 source map 文件（默认为：`false`）(`boolean`) |
+| `--sourcemap [output]`         | 构建后输出 source map 文件（默认为：`false`）(`boolean \| "inline" \| "hidden"`) |
 | `--minify [minifier]`          | 允许或禁用最小化混淆，或指定使用哪种混淆器（默认为：`"esbuild"`）(`boolean \| "terser" \| "esbuild"`) |
 | `--manifest [name]`            | 构建后生成 manifest.json 文件 (`boolean \| string`) |
 | `--ssrManifest [name]`         | 构建后生成 SSR manifest.json 文件 (`boolean \| string`) |

guide/dep-pre-bundling.md

@@ -1,13 +1,6 @@
 # 依赖预构建 {#dependency-pre-bundling}
 
-当你首次启动 `vite` 时，你可能会注意到打印出了以下信息：
-
-```
-Pre-bundling dependencies: （正在预构建依赖：）
-  react
-  react-dom
-(this will be run only when your dependencies or config have changed)（这将只会在你的依赖或配置发生变化时执行）
-```
+当你首次启动 `vite` 时，Vite 在本地加载你的站点之前预构建了项目依赖。默认情况下，它是自动且透明地完成的。
 
 ## 原因 {#the-why}
 
@@ -36,7 +29,7 @@ Pre-bundling dependencies: （正在预构建依赖：）
 
 如果没有找到相应的缓存，Vite 将抓取你的源码，并自动寻找引入的依赖项（即 "bare import"，表示期望从 `node_modules` 解析），并将这些依赖项作为预构建包的入口点。预构建通过 `esbuild` 执行，所以它通常非常快。
 
-在服务器已经启动之后，如果遇到一个新的依赖关系导入，而这个依赖关系还没有在缓存中，Vite 将重新运行依赖构建进程并重新加载页面。
+在服务器已经启动之后，如果遇到一个新的依赖关系导入，而这个依赖关系还没有在缓存中，Vite 将重新运行依赖构建进程并根据需要重新加载页面。
 
 ## Monorepo 和链接依赖 {#monorepos-and-linked-dependencies}
 
@@ -71,6 +64,8 @@ export default defineConfig({
 
 `include` 和 `exclude` 都可以用来处理这个问题。如果依赖项很大（包含很多内部模块）或者是 CommonJS，那么你应该包含它；如果依赖项很小，并且已经是有效的 ESM，则可以排除它，让浏览器直接加载它。
 
+你也可以使用 [`optimizeDeps.esbuildOptions` 选项](/config/dep-optimization-options.md#optimizedeps-esbuildoptions) 来进一步自定义 esbuild。例如，添加一个 esbuild 插件来处理依赖项中的特殊文件。
+
 ## 缓存 {#caching}
 
 ### 文件系统缓存 {#file-system-cache}