docs(cn): update with mainstream

Author: waynzh

.vitepress/config.ts

@@ -39,6 +39,7 @@ export default defineConfig({
     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' },
+    ko: { label: '한국어', link: 'https://ko.vitejs.dev' },
   },
 
   themeConfig: {
@@ -228,11 +229,15 @@ export default defineConfig({
               text: '故障排除',
               link: '/guide/troubleshooting'
             },
+            {
+              text: '理念',
+              link: '/guide/philosophy',
+            },
             {
               text: '从 v3 迁移',
               link: '/guide/migration'
-            }
-          ]
+            },
+          ],
         },
         {
           text: 'API',
@@ -297,13 +302,4 @@ export default defineConfig({
       ]
     }
   },
-
-  markdown: {
-    anchor: {
-      permalink: renderPermaLink
-    },
-    config: (md) => {
-      md.use(MarkDownItCustomAnchor)
-    }
-  }
 })

.vitepress/theme/components/HomeSponsors.vue

@@ -46,7 +46,10 @@ const { data } = useSponsor()
   text-align: center;
   font-weight: 600;
   white-space: nowrap;
-  transition: color 0.25s, border-color 0.25s, background-color 0.25s;
+  transition:
+    color 0.25s,
+    border-color 0.25s,
+    background-color 0.25s;
   /* .VPButton.medium */
   border-radius: 20px;
   padding: 0 20px;

.vitepress/theme/composables/sponsor.ts

@@ -21,8 +21,27 @@ const data = ref()
 const dataHost = 'https://sponsors.vuejs.org'
 const dataUrl = `${dataHost}/vite.json`
 
-// no sponsors yet :(
-const viteSponsors: Pick<Sponsors, 'gold'> = {
+const viteSponsors: Pick<Sponsors, 'special' | 'gold'> = {
+  special: [
+    // sponsors patak-dev
+    {
+      name: 'StackBlitz',
+      url: 'https://stackblitz.com',
+      img: '/stackblitz.svg',
+    },
+    // sponsors antfu
+    {
+      name: 'NuxtLabs',
+      url: 'https://nuxtlabs.com',
+      img: '/nuxtlabs.svg',
+    },
+    // sponsors bluwy
+    {
+      name: 'Astro',
+      url: 'https://astro.build',
+      img: '/astro.svg',
+    },
+  ],
   gold: [],
 }
 
@@ -46,7 +65,12 @@ export function useSponsor() {
 function mapSponsors(sponsors: Sponsors) {
   return [
     {
-      tier: 'Platinum Sponsor',
+      tier: 'Special Sponsors',
+      size: 'big',
+      items: viteSponsors['special'],
+    },
+    {
+      tier: 'Platinum Sponsors',
       size: 'big',
       items: mapImgPath(sponsors['platinum']),
     },
@@ -58,9 +82,20 @@ function mapSponsors(sponsors: Sponsors) {
   ]
 }
 
+const viteSponsorNames = new Set(
+  Object.values(viteSponsors).flatMap((sponsors) =>
+    sponsors.map((s) => s.name),
+  ),
+)
+
+/**
+ * Map Vue/Vite sponsors data to objects and filter out Vite-specific sponsors
+ */
 function mapImgPath(sponsors: Sponsor[]) {
-  return sponsors.map((sponsor) => ({
-    ...sponsor,
-    img: `${dataHost}/images/${sponsor.img}`,
-  }))
+  return sponsors
+    .filter((sponsor) => !viteSponsorNames.has(sponsor.name))
+    .map((sponsor) => ({
+      ...sponsor,
+      img: `${dataHost}/images/${sponsor.img}`,
+    }))
 }

.vitepress/theme/styles/vars.css

@@ -114,3 +114,7 @@
 .dark .vp-doc .custom-block a {
   transition: color 0.25s;
 }
+
+.vp-sponsor.aside .vp-sponsor-grid.mini .vp-sponsor-grid-image {
+  max-width: 124px;
+}

config/build-options.md

@@ -34,7 +34,7 @@ import 'vite/modulepreload-polyfill'
 
 每个动态导入要预加载的块列表将由 Vite 计算。默认情况下，在载入这些依赖时，会使用一个包含 `base` 的绝对路径。如果 `base` 是相对路径（`''` 或者 './'），解析时则会使用 `import.meta.url`，以避免出现依赖于最终部署基路径的绝对路径。
 
-目前有一个实验性功能支持使用 `resolveDependencies` 函数对依赖项列表及其路径进行细粒度控制。它期望接收一个 `ResolveModulePreloadDependenciesFn` 类型的函数:
+目前有一个实验性功能支持使用 `resolveDependencies` 函数对依赖项列表及其路径进行细粒度控制。可以在这里 [提供反馈](https://github.com/vitejs/vite/discussions/13841)。它期望接收一个 `ResolveModulePreloadDependenciesFn` 类型的函数:
 
 ```ts
 type ResolveModulePreloadDependenciesFn = (
@@ -119,10 +119,10 @@ Git LFS 占位符会自动排除在内联之外，因为它们不包含它们所
 
 ## build.cssMinify {#build-cssminify}
 
-- **类型：** `boolean`
+- **类型：** `boolean | 'esbuild' | 'lightningcss'`
 - **默认：** 与 [`build.minify`](#build-minify) 一致
 
-此选项允许用户覆盖 CSS 最小化压缩的配置，而不是使用默认的 `build.minify`，这样你就可以单独配置 JS 和 CSS 的最小化压缩方式。Vite 使用 `esbuild` 来最小化 CSS。
+此选项允许用户覆盖 CSS 最小化压缩的配置，而不是使用默认的 `build.minify`，这样你就可以单独配置 JS 和 CSS 的最小化压缩方式。Vite 默认使用 `esbuild` 来最小化 CSS。将此选项设置为 `'lightningcss'` 可以改用 [Lightning CSS](https://lightningcss.dev/minification.html) 进行压缩。设置为该项，便可以使用 [`css.lightningcss`](./shared-options.md#css-lightningcss) 选项来进行配置。
 
 ## build.sourcemap {#build-sourcemap}
 
@@ -218,7 +218,7 @@ npm add -D terser
 
 ## build.copyPublicDir {#build-copypublicdir}
 
-- **实验性特性**
+- **实验性：** [提供反馈](https://github.com/vitejs/vite/discussions/13807)
 - **类型：** `boolean`
 - **默认：** `true`
 

config/dep-optimization-options.md

@@ -35,7 +35,17 @@ export default defineConfig({
 
 默认情况下，不在 `node_modules` 中的，链接的包不会被预构建。使用此选项可强制预构建链接的包。
 
-## optimizeDeps.esbuildOptions {#optimizedeps-esbuildoptions}
+**实验性：** 如果你使用的是一个有很多深层导入的库，你也可以指定一个尾部的 glob 模式来一次性地预构建所有深层导入。这将避免在使用新的深层导入时不断地预构建。例如：
+
+```js
+export default defineConfig({
+  optimizeDeps: {
+    include: ['my-lib/components/**/*.vue'],
+  },
+})
+```
+
+## optimizeDeps.esbuildOptions {#optimizedeps-esbuild-options}
 
 - **类型：** [`EsbuildBuildOptions`](https://esbuild.github.io/api/#simple-options)
 
@@ -54,7 +64,7 @@ export default defineConfig({
 
 ## optimizeDeps.disabled {#optimizedeps-disabled}
 
-- **实验性**
+- **实验性：** [提供反馈](https://github.com/vitejs/vite/discussions/13839)
 - **类型：** `boolean | 'build' | 'dev'`
 - **默认：** `'build'`
 
@@ -71,5 +81,4 @@ export default defineConfig({
 - **实验性**
 - **类型:** `string[]`
 
-当导入这些依赖项时，会强制 ESM 转换。Vite 能够正确检测到依赖项是否需要转换处理（interop），因此通常不需要使用此选项。然而，不同的依赖项组合可能导致其中一些包以不同方式预构建。将这些包添加到 `needsInterop` 中可以通过避免重新加载整个页面、加快冷启动速度。如果您的某个依赖项符合此情况，Vite 将抛出警告，建议你在配置中添加该包名。
-
+当导入这些依赖项时，会强制 ESM 转换。Vite 能够正确检测到依赖项是否需要转换处理（interop），因此通常不需要使用此选项。然而，不同的依赖项组合可能导致其中一些包以不同方式预构建。将这些包添加到 `needsInterop` 中可以通过避免重新加载整个页面、加快冷启动速度。如果某个依赖项符合此情况，Vite 将抛出警告，建议你在配置中添加该包名。

config/index.md

@@ -1,6 +1,10 @@
+---
+title: 配置 Vite
+---
+
 # 配置 Vite {#configuring-vite}
 
-当以命令行方式运行 `vite` 时，Vite 会自动解析 [项目根目录](/guide/#index-html-and-project-root) 下名为 `vite.config.js` 的文件。
+当以命令行方式运行 `vite` 时，Vite 会自动解析 [项目根目录](/guide/#index-html-and-project-root) 下名为 `vite.config.js` 的配置文件（也支持其他 JS 和 TS 扩展名）。
 
 最基础的配置文件是这样的：
 
@@ -67,7 +71,7 @@ export default defineConfig(({ command, mode, ssrBuild }) => {
 
 ## 异步配置 {#async-config}
 
-如果配置需要调用一个异步函数，也可以转而导出一个异步函数：
+如果配置需要调用一个异步函数，也可以转而导出一个异步函数。这个异步函数也可以通过 `defineConfig` 传递，以便获得更好的智能提示：
 
 ```js
 export default defineConfig(async ({ command, mode }) => {
@@ -94,7 +98,7 @@ export default defineConfig(({ command, mode }) => {
   return {
     // vite 配置
     define: {
-      __APP_ENV__: env.APP_ENV,
+      __APP_ENV__: JSON.stringify(env.APP_ENV),
     },
   }
 })

config/server-options.md

@@ -213,13 +213,11 @@ export default defineConfig({
 ## server.middlewareMode {#server-middlewaremode}
 
 - **类型：** `'ssr' | 'html'`
+- **默认值：** `false`
 
-以中间件模式创建 Vite 服务器。（不含 HTTP 服务器）
+以中间件模式创建 Vite 服务器。
 
-- `'ssr'` 将禁用 Vite 自身的 HTML 服务逻辑，因此你应该手动为 `index.html` 提供服务。
-- `'html'` 将启用 Vite 自身的 HTML 服务逻辑。
-
-- **相关：** [SSR - 设置开发服务器](/guide/ssr#setting-up-the-dev-server)
+- **相关：** [appType](./shared-options#apptype)，[SSR - 设置开发服务器](/guide/ssr#setting-up-the-dev-server)
 
 - **示例：**
 
@@ -239,21 +237,16 @@ async function createServer() {
   app.use(vite.middlewares)
 
   app.use('*', async (req, res) => {
-    // 如果 `middlewareMode` 是 `'ssr'`，应在此为 `index.html` 提供服务.
-    // 如果 `middlewareMode` 是 `'html'`，则此处无需手动服务 `index.html`
-    // 因为 Vite 自会接管
+    // 由于 `appType` 的值是 `'custom'`，因此应在此处提供响应。
+    // 请注意：如果 `appType` 值为 `'spa'` 或 `'mpa'`，Vite 会包含
+    // 处理 HTML 请求和 404 的中间件，因此用户中间件应该在
+    // Vite 的中间件之前添加，以确保其生效。
   })
 }
 
 createServer()
 ```
 
-## server.base {#server-base}
-
-- **类型：** `string | undefined`
-
-在 HTTP 请求中预留此文件夹，用于代理 Vite 作为子文件夹时使用。应该以 `/` 字符开始。
-
 ## server.fs.strict {#server-fs-strict}
 
 - **类型：** `boolean`
@@ -267,6 +260,8 @@ createServer()
 
 限制哪些文件可以通过 `/@fs/` 路径提供服务。当 `server.fs.strict` 设置为 true 时，访问这个目录列表外的文件将会返回 403 结果。
 
+可以提供目录和文件。
+
 Vite 将会搜索此根目录下潜在工作空间并作默认使用。一个有效的工作空间应符合以下几个条件，否则会默认以 [项目 root 目录](/guide/#index-html-and-project-root) 作备选方案。
 
 - 在 `package.json` 中包含 `workspaces` 字段
@@ -299,10 +294,11 @@ export default defineConfig({
         // 搜索工作区的根目录
         searchForWorkspaceRoot(process.cwd()),
         // 自定义规则
-        '/path/to/custom/allow'
-      ]
-    }
-  }
+        '/path/to/custom/allow_directory',
+        '/path/to/custom/allow_file.demo',
+      ],
+    },
+  },
 })
 ```
 
@@ -311,9 +307,7 @@ export default defineConfig({
 - **类型：** `string[]`
 - **默认：** `['.env', '.env.*', '*.{crt,pem}']`
 
-用于限制 Vite 开发服务器提供敏感文件的黑名单。
-
-默认为 `['.env', '.env.*', '*.{pem,crt}']`。这会比 [`server.fs.allow`](#server-fs-allow) 选项的优先级更高。同时还支持 [picomatch patterns](https://github.com/micromatch/picomatch#globbing-features)。
+用于限制 Vite 开发服务器提供敏感文件的黑名单。这会比 [`server.fs.allow`](#server-fs-allow) 选项的优先级更高。同时还支持 [picomatch 模式](https://github.com/micromatch/picomatch#globbing-features)。
 
 ## server.origin {#server-origin}
 

config/shared-options.md

@@ -210,6 +210,8 @@ interface CSSModulesOptions {
 
 配置 CSS modules 的行为。选项将被传递给 [postcss-modules](https://github.com/css-modules/postcss-modules)。
 
+当使用 [Lightning CSS](../guide/features.md#lightning-css) 时，该选项不会产生任何效果。如果要启用该选项，则应该使用 [`css.lightningcss.cssModules`](https://lightningcss.dev/css-modules.html) 来替代。
+
 ## css.postcss {#css-postcss}
 
 - **类型：** `string | (postcss.ProcessOptions & { plugins?: postcss.AcceptedPlugin[] })`
@@ -258,12 +260,52 @@ export default defineConfig({
 
 ## css.devSourcemap {#css-devsourcemap}
 
-- **实验性**
+- **实验性：** [提供反馈](https://github.com/vitejs/vite/discussions/13845)
 - **类型：** `boolean`
 - **默认：** `false`
 
 在开发过程中是否启用 sourcemap。
 
+## css.transformer
+
+- **实验性：** [提供反馈](https://github.com/vitejs/vite/discussions/13835)
+- **类型：** `'postcss' | 'lightningcss'`
+- **默认：** `'postcss'`
+
+该选项用于选择用于 CSS 处理的引擎。详细信息请查看 [Lightning CSS](../guide/features.md#lightning-css)。
+
+## css.lightningcss
+
+- **实验性：** [提供反馈](https://github.com/vitejs/vite/discussions/13835)
+- **类型：**
+
+```js
+import type {
+  CSSModulesConfig,
+  Drafts,
+  Features,
+  NonStandard,
+  PseudoClasses,
+  Targets,
+} from 'lightningcss'
+```
+
+```js
+{
+  targets?: Targets
+  include?: Features
+  exclude?: Features
+  drafts?: Drafts
+  nonStandard?: NonStandard
+  pseudoClasses?: PseudoClasses
+  unusedSymbols?: string[]
+  cssModules?: CSSModulesConfig,
+  // ...
+}
+```
+
+该选项用于配置 Lightning CSS。有关完整的转换选项，请参阅 [Lightning CSS 仓库](https://github.com/parcel-bundler/lightningcss/blob/master/node/index.d.ts)。
+
 ## json.namedExports {#json-namedexports}
 
 - **类型：** `boolean`

config/ssr-options.md

@@ -23,7 +23,8 @@ SSR 服务器的构建目标。
 
 ## ssr.format
 
-- **实验性**
+- **实验性：** [CJS 的支持将在 Vite 5 中移除](https://github.com/vitejs/vite/discussions/13816)
+- **弃用** 在 Vite 5 将只支持 ESM 输出
 - **类型：** `'esm' | 'cjs'`
 - **默认：** `esm`
 

guide/api-hmr.md

@@ -174,6 +174,8 @@ import.meta.hot.accept((module) => {
 - `'vite:beforePrune'` 当不再需要的模块即将被剔除时
 - `'vite:invalidate'` 当使用 `import.meta.hot.invalidate()` 使一个模块失效时
 - `'vite:error'` 当发生错误时（例如，语法错误）
+- `'vite:ws:disconnect'` 当 WebSocket 链接丢失时
+- `'vite:ws:connect'` 当 WebSocket 链接重修建立时
 
 自定义 HMR 事件可以由插件发送。更多细节详见 [handleHotUpdate](./api-plugin#handleHotUpdate)。
 

guide/api-javascript.md

@@ -264,6 +264,10 @@ function mergeConfig(
 
 深度合并两份配置。`isRoot` 代表着 Vite 配置被合并的层级。举个例子，如果你是要合并两个 `build` 选项请设为 `false`。
 
+::: tip NOTE
+`mergeConfig` 只接受对象形式的配置。如果有一个回调形式的配置，应该在将其传递给 `mergeConfig` 之前先调用该回调函数，将其转换成对象形式。
+:::
+
 ## `searchForWorkspaceRoot`
 
 **类型签名：**