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

config/shared-options.md

@@ -37,17 +37,18 @@
 
 定义全局常量替换方式。其中每项在开发环境下会被定义在全局，而在构建时被静态替换。
 
-- String 值会以原始表达式形式使用，所以如果定义了一个字符串常量，**它需要被显式地打引号。**（例如使用 `JSON.stringify`）
+Vite 使用 [esbuild define](https://esbuild.github.io/api/#define) 来进行替换，因此值的表达式必须是一个包含 JSON 可序列化值（null、boolean、number、string、array 或 object）或单一标识符的字符串。对于非字符串值，Vite 将自动使用 `JSON.stringify` 将其转换为字符串。
 
-- 为了与 [esbuild 的行为](https://esbuild.github.io/api/#define)保持一致，表达式必须为一个 JSON 对象（null、boolean、number、string、数组或对象），亦或是一个单独的标识符。
-
-- 替换只会在匹配到周围不是其他字母、数字、`_` 或 `$` 时执行。
-
-::: warning
-因为它是不经过任何语法分析，直接替换文本实现的，所以我们建议只对 CONSTANTS 使用 `define`。
+**示例：**
 
-例如，`process.env.FOO` 和 `__APP_VERSION__` 就非常适合。但 `process` 或 `global` 不应使用此选项。变量相关应使用 shim 或 polyfill 代替。
-:::
+```js
+export default defineConfig({
+  define: {
+    __APP_VERSION__: JSON.stringify('v1.0.0'),
+    __API_URL__: 'window.__backend_api_url',
+  },
+})
+```
 
 ::: tip NOTE
 对于使用 TypeScript 的开发者来说，请确保在 `env.d.ts` 或 `vite-env.d.ts` 文件中添加类型声明，以获得类型检查以及代码提示。
@@ -61,21 +62,7 @@ declare const __APP_VERSION__: string
 
 :::
 
-::: tip NOTE
-由于开发模式和构建模式实现 `define` 的差异性，我们应该避免采用一些可能导致不一致的用例。
-
-例如：
-
-```js
-const obj = {
-  __NAME__, // 不要以缩写形式定义对象属性
-  __KEY__: value // 不要定义对象的 key
-}
-```
-
-:::
-
-## plugins {#plugins}
+## plugins
 
 - **类型：** `(Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]`
 
@@ -154,19 +141,9 @@ Vite 有一个“允许的情景”列表，并且会匹配列表中第一个情
 ## resolve.mainFields {#resolve-mainfields}
 
 - **类型：** `string[]`
-- **默认：** `['module', 'jsnext:main', 'jsnext']`
-
-`package.json` 中，在解析包的入口点时尝试的字段列表。注意：这比从 `exports` 字段解析的情景导出优先级低：如果一个入口点从 `exports` 成功解析，`resolve.mainFields` 将被忽略。
-
-## resolve.browserField {#resolve-browserfield}
-
-- **类型：** `boolean`
-- **默认：** `true`
-- **已废弃**
-
-是否启用对 `browser` 字段的解析。
+- **默认：** `['browser', 'module', 'jsnext:main', 'jsnext']`
 
-在未来，`resolve.mainFields` 的默认值会变成 `['browser', 'module', 'jsnext:main', 'jsnext']` 而这个选项将被移除。
+`package.json` 中，在解析包的入口点时尝试的字段列表。注意：这比从 `exports` 字段解析的情景导出优先级低：如果一个入口起点从 `exports` 成功解析，`resolve.mainFields` 将被忽略。
 
 ## resolve.extensions {#resolve-extensions}
 

guide/migration.md

@@ -32,6 +32,42 @@ CJS 的 Node API 已经被废弃。当调用 `require('vite')` 时，将会记
 
 查看 [排错指南](/guide/troubleshooting.html#vite-cjs-node-api-deprecated) 获取更多信息。
 
+## 重新设计 `define` 和 `import.meta.env.*` 的替换策略 {#rework-define-and-import-meta-env-replacement-strategy}
+
+在 Vite 4 中，`define` 和 `import.meta.env.*` 特性在开发和构建中使用的是不同的替换策略：
+
+- 在开发时，这两个特性分别作为全局变量注入到 `globalThis` 和 `import.meta` 中。
+- 在构建时，这两个特性都使用正则表达式进行静态替换。
+
+这导致在尝试访问这些变量时，开发和构建存在一致性问题，有时甚至导致构建失败。例如：
+
+```js
+// vite.config.js
+export default defineConfig({
+  define: {
+    __APP_VERSION__: JSON.stringify('1.0.0'),
+  },
+})
+```
+
+```js
+const data = { __APP_VERSION__ }
+// 开发：{ __APP_VERSION__: "1.0.0" } ✅
+// 构建：{ "1.0.0" } ❌
+
+const docs = 'I like import.meta.env.MODE'
+// 开发："I like import.meta.env.MODE" ✅
+// 构建："I like "production"" ❌
+```
+
+Vite 5 通过在构建中使用 `esbuild` 来处理替换，使其与开发行为保持一致。
+
+这个改动不应该影响大部分设置，因为已经在文档中说明了 `define` 的值应该遵循 esbuild 的语法：
+
+> 为了与 esbuild 行为保持一致，表达式必须是一个 JSON 对象（null、boolean、number、string、array 或 object）或一个单一标识符字符串。
+
+然而，如果你更喜欢对值直接使用静态替换，你可以使用 [`@rollup/plugin-replace`](https://github.com/rollup/plugins/tree/master/packages/replace)。
+
 ## 其他一般性变化 {#general-changes}
 
 ### SSR 外部模块值现在符合生产环境行为 {#ssr-externalized-modules-value-now-matches-production}
@@ -134,6 +170,8 @@ const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
   - 过去，Vite 对于不带 `Accept: text/html` 的请求，会将其当作带有基础路径的请求来处理。现在 Vite 不再这样做，而是返回 404。
 - [[#14723] fix(resolve)!: remove special .mjs handling](https://github.com/vitejs/vite/pull/14723)
   - 在过去，当一个库的 `"exports"` 字段映射到一个 `.mjs` 文件时，Vite 仍然会尝试匹配 `"browser"` 和 `"module"` 字段，以修复与某些库的兼容性。现在，这种行为已被移除，以便与导出解析算法保持一致。
+- [[#14733] feat(resolve)!: remove `resolve.browserField`](https://github.com/vitejs/vite/pull/14733)
+  - `resolve.browserField` has been deprecated since Vite 3 in favour of an updated default of `['browser', 'module', 'jsnext:main', 'jsnext']` for `resolve.mainFields`。
 
 ## 从 v3 迁移 {#migration-from-v3}
 

guide/static-deploy.md

@@ -96,7 +96,7 @@ $ npm run preview
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
-           uses: actions/checkout@v3
+           uses: actions/checkout@v4
          - name: Set up Node
            uses: actions/setup-node@v3
            with:
@@ -109,13 +109,13 @@ $ npm run preview
          - name: Setup Pages
            uses: actions/configure-pages@v3
          - name: Upload artifact
-           uses: actions/upload-pages-artifact@v1
+           uses: actions/upload-pages-artifact@v2
            with:
              # Upload dist repository
              path: './dist'
          - name: Deploy to GitHub Pages
            id: deployment
-           uses: actions/deploy-pages@v1
+           uses: actions/deploy-pages@v2
    ```
 
 ## GitLab Pages 配合 GitLab CI {#gitlab-pages-and-gitlab-ci}