docs(en): merge docs-cn/sync-docs into docs-cn/dev @ 4932528a

.vitepress/config.ts

@@ -529,7 +529,11 @@ export default defineConfig({
     languages: ['ts', 'js', 'json'],
     codeTransformers: [transformerTwoslash()],
     config(md) {
-      md.use(groupIconMdPlugin)
+      md.use(groupIconMdPlugin, {
+        titleBar: {
+          includeSnippet: true,
+        },
+      })
       md.use(markdownItImageSize, {
         publicDir: path.resolve(import.meta.dirname, '../public'),
       })

guide/api-environment-plugins.md

@@ -146,7 +146,7 @@ interface HotUpdateOptions {
 
 ## 插件中的基于环境的状态 {#per-environment-state-in-plugins}
 
-鉴于相同的插件实例会被用于不同的环境，插件的状态需要以 `this.environment` 作为键来存储。这与生态系统中已使用的模式相同，即使用 `ssr` 布尔值作为键来避免混合客户端和 SSR 模块状态的方式。可以使用 `Map<Environment, State>` 来分别为每个环境保存其对应的状态。注意：为了保持向后兼容性，在未设置 `perEnvironmentStartEndDuringDev: true` 标志时，`buildStart` 和 `buildEnd` 仅会针对客户端环境被调用。
+鉴于相同的插件实例会被用于不同的环境，插件的状态需要以 `this.environment` 作为键来存储。这与生态系统中已使用的模式相同，即使用 `ssr` 布尔值作为键来避免混合客户端和 SSR 模块状态的方式。可以使用 `Map<Environment, State>` 来分别为每个环境保存其对应的状态。注意：为了保持向后兼容性，在未设置 `perEnvironmentStartEndDuringDev: true` 标志时，`buildStart` 和 `buildEnd` 仅会针对客户端环境被调用。同样的规则也适用于 `watchChange` 和 `perEnvironmentWatchChangeDuringDev: true` 标志。
 
 ```js
 function PerEnvironmentCountTransformedModulesPlugin() {
@@ -227,6 +227,43 @@ export default defineConfig({
 
 `applyToEnvironment` 钩子在配置时调用，目前在 `configResolved` 之后调用，因为生态系统中的项目正在修改其中的插件。未来，环境插件解析可能会移至 `configResolved` 之前。
 
+## 应用程序-插件通信 {#application-plugin-communication}
+
+`environment.hot` 允许插件与给定环境的应用程序端代码进行通信。这相当于[客户端-服务器通信功能](/guide/api-plugin#client-server-communication)，但支持除客户端环境以外的其他环境。
+
+:::warning Note
+
+请注意，此功能仅适用于支持 HMR 的环境。
+
+:::
+
+### 管理应用程序实例 {#managing-the-application-instances}
+
+需要注意的是，在同一环境中可能有多个应用程序实例在运行。例如，如果你在浏览器中打开了多个标签页，每个标签页都是一个独立的应用程序实例，并且与服务器有独立的连接。
+
+当建立新连接时，会在环境的 `hot` 实例上触发 `vite:client:connect` 事件。当连接关闭时，会触发 `vite:client:disconnect` 事件。
+
+每个事件处理程序都会接收到 `NormalizedHotChannelClient` 作为第二个参数。客户端是一个具有 `send` 方法的对象，可用于向该特定应用程序实例发送消息。对于同一连接，客户端引用始终相同，因此你可以保留它来跟踪连接。
+
+### 使用示例 {#example-usage}
+
+插件端：
+
+```js
+configureServer(server) {
+  server.environments.ssr.hot.on('my:greetings', (data, client) => {
+    // 处理数据，
+    // 并可选择向该应用程序实例发送响应
+    client.send('my:foo:reply', `Hello from server! You said: ${data}`)
+  })
+
+  // 向所有应用程序实例广播消息
+  server.environments.ssr.hot.send('my:foo', 'Hello from server!')
+}
+```
+
+应用程序端与客户端-服务器通信功能相同。您可以使用 `import.meta.hot` 对象向插件发送消息。
+
 ## 构建钩子中的环境 {#environment-in-build-hooks}
 
 与开发期间一样，插件钩子在构建期间也接收环境实例，取代了 `ssr` 布尔值。

guide/api-environment-runtimes.md

@@ -316,27 +316,45 @@ import { createServer, RemoteEnvironmentTransport, DevEnvironment } from 'vite'
 function createWorkerEnvironment(name, config, context) {
   const worker = new Worker('./worker.js')
   const handlerToWorkerListener = new WeakMap()
+  const client = {
+    send(payload: HotPayload) {
+      worker.postMessage(payload)
+    },
+  }
 
   const workerHotChannel = {
     send: (data) => worker.postMessage(data),
     on: (event, handler) => {
-      if (event === 'connection') return
+      // client is already connected
+      if (event === 'vite:client:connect') return
+      if (event === 'vite:client:disconnect') {
+        const listener = () => {
+          handler(undefined, client)
+        }
+        handlerToWorkerListener.set(handler, listener)
+        worker.on('exit', listener)
+        return
+      }
 
       const listener = (value) => {
         if (value.type === 'custom' && value.event === event) {
-          const client = {
-            send(payload) {
-              worker.postMessage(payload)
-            },
-          }
           handler(value.data, client)
         }
       }
       handlerToWorkerListener.set(handler, listener)
       worker.on('message', listener)
     },
     off: (event, handler) => {
-      if (event === 'connection') return
+      if (event === 'vite:client:connect') return
+      if (event === 'vite:client:disconnect') {
+        const listener = handlerToWorkerListener.get(handler)
+        if (listener) {
+          worker.off('exit', listener)
+          handlerToWorkerListener.delete(handler)
+        }
+        return
+      }
+
       const listener = handlerToWorkerListener.get(handler)
       if (listener) {
         worker.off('message', listener)
@@ -363,6 +381,8 @@ await createServer({
 
 :::
 
+请确保在 `on` / `off` 方法存在时实现 `vite:client:connect` / `vite:client:disconnect` 事件。当连接建立时应触发 `vite:client:connect` 事件，当连接关闭时应触发 `vite:client:disconnect` 事件。传递给事件处理程序的 `HotChannelClient` 对象对于同一连接必须具有相同的引用。
+
 使用 HTTP 请求在运行程序和服务器之间进行通信的另一个示例：
 
 ```ts

guide/static-deploy.md

@@ -63,7 +63,7 @@ $ npm run preview
 
 2. 进入仓库 settings 页面的 GitHub Pages 配置，选择部署来源为“GitHub Actions”，这将引导你创建一个构建和部署项目的工作流程，我们提供了一个安装依赖项和使用 npm 构建的工作流程样本：
 
-   <<< ./static-deploy-github-pages.yaml#content
+   <<< ./static-deploy-github-pages.yaml#content [.github/workflows/deploy.yml]
 
 ## GitLab Pages 配合 GitLab CI {#gitlab-pages-and-gitlab-ci}
 

package.json

@@ -8,9 +8,9 @@
 	"private": true,
 	"license": "CC BY-NC-SA 4.0",
 	"devDependencies": {
-		"@shikijs/vitepress-twoslash": "^3.13.0",
+		"@shikijs/vitepress-twoslash": "^3.14.0",
 		"@type-challenges/utils": "^0.1.1",
-		"@types/express": "^5.0.3",
+		"@types/express": "^5.0.4",
 		"@types/node": "^20.9.2",
 		"chalk": "^4.1.2",
 		"feed": "^5.1.0",
@@ -20,10 +20,10 @@
 		"markdown-it-image-size": "^15.0.1",
 		"vite": "^7.0.4",
 		"vitepress": "^2.0.0-alpha.7",
-		"vitepress-plugin-group-icons": "^1.6.4",
-		"vitepress-plugin-llms": "^1.8.0",
+		"vitepress-plugin-group-icons": "^1.6.5",
+		"vitepress-plugin-llms": "^1.8.1",
 		"vue": "^3.5.22",
-		"vue-tsc": "^3.1.1",
+		"vue-tsc": "^3.1.2",
 		"yorkie": "^2.0.0"
 	},
 	"packageManager": "pnpm@9.6.0",