Merge pull request #930 from vitejs/sync-7d52e910-1

docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 7d52e91

Author: waynzh

.vitepress/config.ts

@@ -1,4 +1,5 @@
 import { defineConfig, DefaultTheme } from 'vitepress'
+import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { buildEnd } from './buildEnd.config'
 
 const ogDescription = 'Next Generation Frontend Tooling'
@@ -393,5 +394,8 @@ export default defineConfig({
     ])
     return pageData
   },
+  markdown: {
+    codeTransformers: [transformerTwoslash()],
+  },
   buildEnd,
 })

.vitepress/theme/composables/sponsor.ts

@@ -1,4 +1,4 @@
-import { ref, onMounted } from 'vue'
+import { ref, onMounted, onUnmounted } from 'vue'
 
 interface Sponsors {
   special: Sponsor[]
@@ -13,6 +13,10 @@ interface Sponsor {
   name: string
   img: string
   url: string
+  /**
+   * Expects to also have an **inversed** image with `-dark` postfix.
+   */
+  hasDark?: true
 }
 
 // shared data across instances so we load only once.
@@ -58,12 +62,40 @@ const viteSponsors: Pick<Sponsors, 'special' | 'gold'> = {
       name: 'Transloadit',
       url: 'https://transloadit.com/?utm_source=vite&utm_medium=referral&utm_campaign=sponsorship&utm_content=website',
       img: '/transloadit.svg',
+      hasDark: true,
     },
   ],
 }
 
+function toggleDarkLogos() {
+  if (data.value) {
+    const isDark = document.documentElement.classList.contains('dark')
+    data.value.forEach(({ items }) => {
+      items.forEach((s: Sponsor) => {
+        if (s.hasDark) {
+          s.img = isDark
+            ? s.img.replace(/(\.\w+)$/, '-dark$1')
+            : s.img.replace(/-dark(\.\w+)$/, '$1')
+        }
+      })
+    })
+  }
+}
+
 export function useSponsor() {
   onMounted(async () => {
+    const ob = new MutationObserver((list) => {
+      for (const m of list) {
+        if (m.attributeName === 'class') {
+          toggleDarkLogos()
+        }
+      }
+    })
+    ob.observe(document.documentElement, { attributes: true })
+    onUnmounted(() => {
+      ob.disconnect()
+    })
+
     if (data.value) {
       return
     }
@@ -72,6 +104,7 @@ export function useSponsor() {
     const json = await result.json()
 
     data.value = mapSponsors(json)
+    toggleDarkLogos()
   })
 
   return {

.vitepress/theme/index.ts

@@ -1,6 +1,8 @@
 import { h } from 'vue'
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
+import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
+import '@shikijs/vitepress-twoslash/style.css'
 import './styles/vars.css'
 import HomeSponsors from './components/HomeSponsors.vue'
 import AsideSponsors from './components/AsideSponsors.vue'
@@ -19,6 +21,7 @@ export default {
   },
   enhanceApp({ app }) {
     app.component('SvgImage', SvgImage)
+    app.use(TwoslashFloatingVue)
   },
 } satisfies Theme
 

.vitepress/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "esModuleInterop": true,
+    "noEmit": true
+  },
+  "exclude": ["cache", "dist"]
+}

config/build-options.md

@@ -48,13 +48,22 @@ type ResolveModulePreloadDependenciesFn = (
 
 `resolveDependencies` 函数将为每个动态导入调用，同时带着一个它所依赖的 chunk 列表。并且它还会为每个在入口 HTML 文件中导入的 chunk 调用。 可以返回一个新的依赖关系数组，可能被过滤后变少了，也可能有更多依赖注入进来了，同时它们的路径也被修改过。`deps` 路径是相对于 `build.outDir` 的。若在注入该模块到 HTML head 时使用 `new URL(dep, import.meta.url)` 获取绝对路径，则对于 `hostType === 'js'`，允许返回一个相对于 `hostId` 的路径。
 
-```js
+<!-- prettier-ignore-start -->
+```js twoslash
+/** @type {import('vite').UserConfig} */
+const config = {
+  build: {
+// ---cut-before---
 modulePreload: {
   resolveDependencies: (filename, deps, { hostId, hostType }) => {
     return deps.filter(condition)
-  }
+  },
+},
+// ---cut-after---
+  },
 }
 ```
+<!-- prettier-ignore-end -->
 
 解析得到的依赖路径可以再在之后使用 [`experimental.renderBuiltUrl`](../guide/build.md#advanced-base-options) 更改。
 

config/dep-optimization-options.md

@@ -19,7 +19,9 @@
 :::warning CommonJS
 CommonJS 的依赖不应该排除在优化外。如果一个 ESM 依赖被排除在优化外，但是却有一个嵌套的 CommonJS 依赖，则应该为该 CommonJS 依赖添加 `optimizeDeps.include`。例如：
 
-```js
+```js twoslash
+import { defineConfig } from 'vite'
+// ---cut---
 export default defineConfig({
   optimizeDeps: {
     include: ['esm-dep > cjs-dep'],
@@ -37,7 +39,9 @@ export default defineConfig({
 
 **实验性：** 如果你使用的是一个有很多深层导入的库，你也可以指定一个尾部的 glob 模式来一次性地预构建所有深层导入。这将避免在使用新的深层导入时不断地预构建。可以在此 [提供反馈](https://github.com/vitejs/vite/discussions/15833)。例如：
 
-```js
+```js twoslash
+import { defineConfig } from 'vite'
+// ---cut---
 export default defineConfig({
   optimizeDeps: {
     include: ['my-lib/components/**/*.vue'],

config/index.md

@@ -50,7 +50,9 @@ Vite 也直接支持 TS 配置文件。你可以在 `vite.config.ts` 中使用 `
 
 如果配置文件需要基于（`dev`/`serve` 或 `build`）命令或者不同的 [模式](/guide/env-and-mode) 来决定选项，亦或者是一个 SSR 构建（`isSsrBuild`）、一个正在预览的构建产物（`isPreview`），则可以选择导出这样一个函数：
 
-```js
+```js twoslash
+import { defineConfig } from 'vite'
+// ---cut---
 export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
   if (command === 'serve') {
     return {
@@ -65,15 +67,17 @@ export default defineConfig(({ command, mode, isSsrBuild, isPreview }) => {
 })
 ```
 
-需要注意的是，在 Vite 的 API 中，在开发环境下 `command` 的值为 `serve`（在 CLI 中， `vite dev` 和 `vite serve` 是 `vite` 的别名），而在生产环境下为 `build`（`vite build`）。
+需要注意的是，在 Vite 的 API 中，在开发环境下 `command` 的值为 `serve`（在 CLI 中， `vite dev` 和 `vite serve` 是 [`vite`](/guide/cli#vite) 的别名），而在生产环境下为 `build`（[`vite build`](/guide/cli#vite-build)）。
 
 `isSsrBuild` 和 `isPreview` 是额外的可选标志，用于区分 `build` 和 `serve` 命令的类型。一些加载 Vite 配置的工具可能不支持这些标志，而会传递 `undefined`。因此，建议使用 `true` 和 `false` 的显式比较。
 
 ## 异步配置 {#async-config}
 
 如果配置需要调用一个异步函数，也可以转而导出一个异步函数。这个异步函数也可以通过 `defineConfig` 传递，以便获得更好的智能提示：
 
-```js
+```js twoslash
+import { defineConfig } from 'vite'
+// ---cut---
 export default defineConfig(async ({ command, mode }) => {
   const data = await asyncFunction()
   return {
@@ -88,7 +92,7 @@ export default defineConfig(async ({ command, mode }) => {
 
 注意 Vite 默认是不加载 `.env` 文件的，因为这些文件需要在执行完 Vite 配置后才能确定加载哪一个，举个例子，`root` 和 `envDir` 选项会影响加载行为。不过当你的确需要时，你可以使用 Vite 导出的 `loadEnv` 函数来加载指定的 `.env` 文件。
 
-```js
+```js twoslash
 import { defineConfig, loadEnv } from 'vite'
 
 export default defineConfig(({ command, mode }) => {

config/server-options.md

@@ -18,10 +18,10 @@
 
 你可以设置 [`dns.setDefaultResultOrder('verbatim')`](https://nodejs.org/api/dns.html#dns_dns_setdefaultresultorder_order) 来禁用这个重新排序的行为。Vite 会将地址打印为 `localhost`。
 
-```js
+```js twoslash
 // vite.config.js
 import { defineConfig } from 'vite'
-import dns from 'dns'
+import dns from 'node:dns'
 
 dns.setDefaultResultOrder('verbatim')
 
@@ -152,6 +152,8 @@ export default defineConfig({
 
 设置 `server.hmr.overlay` 为 `false` 可以禁用开发服务器错误的屏蔽。
 
+`protocol` 是用于设置 HMR 连接使用的 WebSocket 协议的选项，可以是 `ws`（WebSocket）或者 `wss`（WebSocket Secure）。
+
 `clientPort` 是一个高级选项，只在客户端的情况下覆盖端口，这允许你为 websocket 提供不同的端口，而并非在客户端代码中查找。如果需要在 dev-server 情况下使用 SSL 代理，这非常有用。
 
 当 `server.hmr.server` 被定义后，Vite 将会通过所提供的的服务器来处理 HMR 连接。如果不是在中间件模式下，Vite 将尝试通过已有服务器处理 HMR 连接。这在使用自签证书或想通过网络在某端口暴露 Vite 的情况下，非常有用。
@@ -236,7 +238,7 @@ Vite 服务器的文件监听器默认会监听 `root` 目录，同时会跳过
 
 - **示例：**
 
-```js
+```js twoslash
 import express from 'express'
 import { createServer as createViteServer } from 'vite'
 
@@ -356,9 +358,9 @@ export default defineConfig({
     // 添加到忽略列表中。
     sourcemapIgnoreList(sourcePath, sourcemapPath) {
       return sourcePath.includes('node_modules')
-    }
-  }
-};
+    },
+  },
+})
 ```
 
 ::: tip 注意

config/shared-options.md

@@ -163,7 +163,14 @@ 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}
+## html.cspNonce
+
+- **类型：** `string`
+- **相关：** [内容安全策略（CSP）](/guide/features#content-security-policy-csp)
+
+一个在生成脚本或样式标签时会用到的 nonce 值占位符。设置此值还会生成一个带有 nonce 值的 meta 标签。
+
+## css.modules
 
 - **类型：**
   ```ts
@@ -408,7 +415,7 @@ export default defineConfig({
 
 使用自定义 logger 记录消息。可以使用 Vite 的 `createLogger` API 获取默认的 logger 并对其进行自定义，例如，更改消息或过滤掉某些警告。
 
-```js
+```ts twoslash
 import { createLogger, defineConfig } from 'vite'
 
 const logger = createLogger()

config/ssr-options.md

@@ -18,7 +18,7 @@
 
 这个选项可以防止列出的依赖项在服务端渲染（SSR）时被外部化，这些依赖项将会在构建过程中被打包。默认情况下，只有软链接的依赖项不会被外部化（这是为了HMR）。如果你希望将软链接的依赖项也外部化，可以将其名称传给 `ssr.external` 选项。
 
-如果这个选项设置为 `true`，那么没有任何依赖项会被外部化。然而，如果你在 `ssr.external` 中明确列出了一些依赖项（使用 `string[]` 类型），那么这些依赖项可以优先被外部化。
+如果这个选项设置为 `true`，那么没有任何依赖项会被外部化。然而，如果你在 `ssr.external` 中明确列出了一些依赖项（使用 `string[]` 类型），那么这些依赖项可以优先被外部化。如果设置了 `ssr.target: 'node'`，那么 Node.js 的内置模块也会被默认外部化。
 
 需要注意的是，如果 `ssr.noExternal: true` 和 `ssr.external: true` 都被设置了，那么 `ssr.noExternal` 将优先生效，没有任何依赖项会被外部化。
 

guide/api-hmr.md

@@ -8,15 +8,15 @@
 
 Vite 通过特殊的 `import.meta.hot` 对象暴露手动 HMR API。
 
-```ts
+```ts twoslash
+import type { ModuleNamespace } from 'vite/types/hot.d.ts'
+import type { InferCustomEventPayload } from 'vite/types/customEvent.d.ts'
+
+// ---cut---
 interface ImportMeta {
   readonly hot?: ViteHotContext
 }
 
-type ModuleNamespace = Record<string, any> & {
-  [Symbol.toStringTag]: 'Module'
-}
-
 interface ViteHotContext {
   readonly data: any
 
@@ -32,7 +32,6 @@ interface ViteHotContext {
   prune(cb: (data: any) => void): void
   invalidate(message?: string): void
 
-  // `InferCustomEventPayload` provides types for built-in Vite events
   on<T extends string>(
     event: T,
     cb: (payload: InferCustomEventPayload<T>) => void,
@@ -66,7 +65,9 @@ Vite 在 [`vite/client.d.ts`](https://github.com/vitejs/vite/blob/main/packages/
 
 要接收模块自身，应使用 `import.meta.hot.accept`，参数为接收已更新模块的回调函数：
 
-```js
+```js twoslash
+import 'vite/client'
+// ---cut---
 export const count = 1
 
 if (import.meta.hot) {
@@ -89,7 +90,13 @@ Vite 要求这个函数的调用在源代码中显示为 `import.meta.hot.accept
 
 模块也可以接受直接依赖项的更新，而无需重新加载自身：
 
-```js
+```js twoslash
+// @filename: /foo.d.ts
+export declare const foo: () => void
+
+// @filename: /example.js
+import 'vite/client'
+// ---cut---
 import { foo } from './foo.js'
 
 foo()
@@ -115,7 +122,9 @@ if (import.meta.hot) {
 
 一个接收自身的模块或一个期望被其他模块接收的模块可以使用 `hot.dispose` 来清除任何由其更新副本产生的持久副作用：
 
-```js
+```js twoslash
+import 'vite/client'
+// ---cut---
 function setupSideEffect() {}
 
 setupSideEffect()
@@ -131,7 +140,9 @@ if (import.meta.hot) {
 
 注册一个回调，当模块在页面上不再被导入时调用。与 `hot.dispose` 相比，如果源代码更新时自行清理了副作用，你只需要在模块从页面上被删除时，使用此方法进行清理。Vite 目前在 `.css` 导入上使用此方法。
 
-```js
+```js twoslash
+import 'vite/client'
+// ---cut---
 function setupOrReuseSideEffect() {}
 
 setupOrReuseSideEffect()
@@ -149,7 +160,9 @@ if (import.meta.hot) {
 
 注意，不支持对 `data` 本身的重新赋值。相反，你应该对 `data` 对象的属性进行突变，以便保留从其他处理程序添加的信息。
 
-```js
+```js twoslash
+import 'vite/client'
+// ---cut---
 // ok
 import.meta.hot.data.someValue = 'hello'
 
@@ -167,7 +180,9 @@ import.meta.hot.data = { someValue: 'hello' }
 
 请注意，你应该总是调用 `import.meta.hot.accept`，即使你打算随后立即调用 `invalidate`，否则 HMR 客户端将不会监听未来对接收自身模块的更改。为了清楚地表达你的意图，我们建议在 `accept` 回调中调用 `invalidate`，例如：
 
-```js
+```js twoslash
+import 'vite/client'
+// ---cut---
 import.meta.hot.accept((module) => {
   // 你可以使用新的模块实例来决定是否使其失效。
   if (cannotHandleUpdate(module)) {