@modern-js/main-doc 3.9.2 → 3.10.0

package/docs/zh/configure/app/server/tsconfig-path.mdx

@@ -40,9 +40,9 @@ title: tsconfigPath
     "types": ["node"],
     "esModuleInterop": true,
     "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
+    "emitDecoratorMetadata": true,
   },
-  "include": ["api", "shared", "server", "config", "modern.config.ts"]
+  "include": ["api", "shared", "server", "config", "modern.config.ts"],
 }
 ```
 

package/docs/zh/configure/app/tools/less.mdx

@@ -9,49 +9,78 @@ title: less
 
 ```js
 const defaultOptions = {
-  lessOptions: {
-    javascriptEnabled: true,
+  lessLoaderOptions: {
+    lessOptions: {
+      javascriptEnabled: true,
+    },
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
   },
-  // 默认在开发环境下启用 CSS 的 Source Map
-  sourceMap: isDev,
 };
 ```
 
-你可以通过 `tools.less` 修改 [less-loader](https://github.com/webpack-contrib/less-loader) 的配置。
+`tools.less` 用于修改 [@rsbuild/plugin-less](https://rsbuild.rs/plugins/list/plugin-less) 的选项，取值为该插件的完整选项：
+
+| 选项                | 说明                                                                                      |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `lessLoaderOptions` | 传给 [less-loader](https://github.com/webpack-contrib/less-loader) 的选项，支持对象或函数 |
+| `include`           | 指定哪些文件交给 less-loader 处理，默认 `/\.less$/`                                       |
+| `exclude`           | 指定哪些文件不交给 less-loader 处理                                                       |
+| `parallel`          | 是否使用 worker 线程并行编译 Less，默认 `false`                                           |
+
+### 修改 less-loader 选项
 
-### Object 类型
+`lessLoaderOptions` 为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`lessOptions` 会通过 deepMerge 进行深层合并。
+
+```js
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: {
+          javascriptEnabled: false,
+        },
+      },
+    },
+  },
+};
+```
 
-当 `tools.less` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`lessOptions` 会通过 deepMerge 进行深层合并。
+`lessLoaderOptions` 为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
 
 ```js
 export default {
   tools: {
     less: {
-      lessOptions: {
-        javascriptEnabled: false,
+      lessLoaderOptions(config) {
+        // 修改 lessOptions 配置
+        config.lessOptions = {
+          javascriptEnabled: false,
+        };
       },
     },
   },
 };
 ```
 
-### Function 类型
+### 并行编译
 
-当 `tools.less` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+Less 编译是纯 JavaScript 计算，默认只占用 Node.js 主线程。开启 `parallel` 后，Less 模块会分发到 worker 线程池中编译，项目里 Less 文件较多时可以缩短构建时间。
 
 ```js
 export default {
   tools: {
-    less(config) {
-      // 修改 lessOptions 配置
-      config.lessOptions = {
-        javascriptEnabled: false,
-      };
+    less: {
+      parallel: true,
     },
   },
 };
 ```
 
+:::tip
+传给 worker 线程的选项需要满足[结构化克隆算法](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)的要求，因此开启 `parallel` 后，`lessLoaderOptions` 中不能包含函数，例如 `additionalData` 函数或自定义的 `implementation`。
+:::
+
 ### 修改 Less 版本
 
 在某些场景下，如果你需要使用特定的 Less 版本，而不是使用 Modern.js 内置的 Less v4，可以在项目中安装需要使用的 Less 版本，并通过 `less-loader` 的 `implementation` 选项设置。
@@ -60,7 +89,9 @@ export default {
 export default {
   tools: {
     less: {
-      implementation: require('less'),
+      lessLoaderOptions: {
+        implementation: require('less'),
+      },
     },
   },
 };
@@ -77,10 +108,53 @@ export default {
 ```js
 export default {
   tools: {
-    less(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    less: {
+      lessLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
     },
   },
 };
 ```
 
+推荐直接使用插件的 `exclude` 选项，效果相同：
+
+```js
+export default {
+  tools: {
+    less: {
+      exclude: /node_modules/,
+    },
+  },
+};
+```
+
+### 兼容旧写法
+
+:::warning 不要混写两种层级
+同一个对象里只要出现插件顶层键（`lessLoaderOptions`、`include`、`exclude` 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 `tools.less: { parallel: true, lessOptions: { ... } }` 里的 `lessOptions` 会被忽略，必须移到 `lessLoaderOptions` 下；开发环境下会打印一条提示。
+:::
+
+在之前的版本中，`tools.less` 的取值直接是 less-loader 的选项，例如 `tools.less: { lessOptions: {} }` 或 `tools.less(config, { addExcludes }) {}`。这种写法目前仍然生效，Modern.js 会自动把它包装为 `lessLoaderOptions`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。
+
+```js
+// 旧写法
+export default {
+  tools: {
+    less: {
+      lessOptions: { javascriptEnabled: false },
+    },
+  },
+};
+
+// 新写法
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: { javascriptEnabled: false },
+      },
+    },
+  },
+};
+```

package/docs/zh/configure/app/tools/sass.mdx

@@ -9,39 +9,64 @@ title: sass
 
 ```js
 const defaultOptions = {
-  // 默认在开发环境下启用 CSS 的 Source Map
-  sourceMap: isDev,
+  sassLoaderOptions: {
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
+  },
 };
 ```
 
-你可以通过 `tools.sass` 修改 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的配置。
+`tools.sass` 用于修改 [@rsbuild/plugin-sass](https://rsbuild.rs/plugins/list/plugin-sass) 的选项，取值为该插件的完整选项：
+
+| 选项                | 说明                                                                                      |
+| ------------------- | ----------------------------------------------------------------------------------------- |
+| `sassLoaderOptions` | 传给 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的选项，支持对象或函数 |
+| `include`           | 指定哪些文件交给 sass-loader 处理，默认 `/\.s(?:a\|c)ss$/`                                |
+| `exclude`           | 指定哪些文件不交给 sass-loader 处理                                                       |
+| `rewriteUrls`       | 是否使用 resolve-url-loader 重写 Sass 文件中的相对 URL，默认 `true`                       |
 
-### Object 类型
+### 修改 sass-loader 选项
 
-当 `tools.sass` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`sassOptions` 会通过 deepMerge 进行深层合并。
+`sassLoaderOptions` 为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`sassOptions` 会通过 deepMerge 进行深层合并。
 
 ```js
 export default {
   tools: {
     sass: {
-      sourceMap: true,
+      sassLoaderOptions: {
+        sourceMap: true,
+      },
     },
   },
 };
 ```
 
-### Function 类型
+`sassLoaderOptions` 为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    sass: {
+      sassLoaderOptions(config) {
+        // 修改 additionalData 配置
+        config.additionalData = async (content, loaderContext) => {
+          // ...
+        };
+      },
+    },
+  },
+};
+```
 
-当 `tools.sass` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+### 关闭 URL 重写
+
+默认情况下，Sass 文件里的相对 URL 会经过 resolve-url-loader 重写为相对于源文件的路径。如果项目不依赖这一行为，可以关闭它来减少一个 loader：
 
 ```js
 export default {
   tools: {
-    sass(config) {
-      // 修改 sourceMap 配置
-      config.additionalData = async (content, loaderContext) => {
-        // ...
-      };
+    sass: {
+      rewriteUrls: false,
     },
   },
 };
@@ -55,7 +80,9 @@ export default {
 export default {
   tools: {
     sass: {
-      implementation: require('sass'),
+      sassLoaderOptions: {
+        implementation: require('sass'),
+      },
     },
   },
 };
@@ -72,8 +99,52 @@ export default {
 ```js
 export default {
   tools: {
-    sass(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    sass: {
+      sassLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
+    },
+  },
+};
+```
+
+推荐直接使用插件的 `exclude` 选项，效果相同：
+
+```js
+export default {
+  tools: {
+    sass: {
+      exclude: /node_modules/,
+    },
+  },
+};
+```
+
+### 兼容旧写法
+
+:::warning 不要混写两种层级
+同一个对象里只要出现插件顶层键（`sassLoaderOptions`、`include`、`exclude` 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 `tools.sass: { rewriteUrls: false, sassOptions: { ... } }` 里的 `sassOptions` 会被忽略，必须移到 `sassLoaderOptions` 下；开发环境下会打印一条提示。
+:::
+
+在之前的版本中，`tools.sass` 的取值直接是 sass-loader 的选项，例如 `tools.sass: { sassOptions: {} }` 或 `tools.sass(config, { addExcludes }) {}`。这种写法目前仍然生效，Modern.js 会自动把它包装为 `sassLoaderOptions`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。
+
+```js
+// 旧写法
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+
+// 新写法
+export default {
+  tools: {
+    sass: {
+      sassLoaderOptions: {
+        sourceMap: true,
+      },
     },
   },
 };

package/docs/zh/configure/app/tools/svgr.mdx

@@ -0,0 +1,93 @@
+---
+title: svgr
+---
+
+# tools.svgr
+
+- **类型：** `Object | Function | false`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  mixedImport: true,
+  svgrOptions: {
+    exportType: 'named',
+  },
+};
+```
+
+`tools.svgr` 用于修改 [@rsbuild/plugin-svgr](https://rsbuild.rs/plugins/list/plugin-svgr) 的选项，取值为该插件的完整选项。设置为 `false` 时不再注册 SVGR 插件，所有 `.svg` 文件按静态资源处理。
+
+| 选项              | 说明                                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
+| `svgrOptions`     | 传给 [SVGR](https://react-svgr.com/docs/options/) 的参数，例如 `exportType`、`icon`、`svgoConfig` |
+| `parallel`        | 是否使用 worker 线程并行转换 SVG，默认 `false`                                                    |
+| `exclude`         | 指定哪些 SVG 文件不交给 SVGR 处理                                                                 |
+| `excludeImporter` | 指定从哪些文件导入 SVG 时不交给 SVGR 处理                                                         |
+| `query`           | 指定触发 SVGR 转换的 query，默认 `/react/`                                                        |
+| `mixedImport`     | 是否允许在同一个模块中同时导入 URL 与 React 组件，默认 `true`                                     |
+
+### 合并规则
+
+`tools.svgr` 为 `Object` 类型时，顶层字段与默认配置通过 Object.assign 进行浅层合并，`svgrOptions` 会再合并一层，因此只设置 `svgrOptions.icon` 不会丢掉默认的 `exportType`。
+
+`tools.svgr` 为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。也支持传入由对象和函数组成的数组，按顺序依次应用。
+
+### 并行转换
+
+SVGR 转换是纯 JavaScript 计算，默认只占用 Node.js 主线程。项目里 SVG 文件较多时，开启 `parallel` 可以把转换分发到 worker 线程池：
+
+```js
+export default {
+  tools: {
+    svgr: {
+      parallel: true,
+    },
+  },
+};
+```
+
+:::tip
+传给 worker 线程的选项需要满足[结构化克隆算法](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)的要求，因此开启 `parallel` 后，`svgrOptions` 中不能包含函数。
+:::
+
+### 修改默认导出
+
+`svgrOptions.exportType` 决定 SVG 文件默认导出的内容：`'named'` 表示默认导出是文件 URL，React 组件通过 `ReactComponent` 具名导出；`'default'` 表示默认导出就是 React 组件。
+
+```js
+export default {
+  tools: {
+    svgr: {
+      svgrOptions: {
+        exportType: 'default',
+      },
+    },
+  },
+};
+```
+
+### 关闭 SVGR
+
+如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用，可以关闭 SVGR 以提升构建性能：
+
+```js
+export default {
+  tools: {
+    svgr: false,
+  },
+};
+```
+
+### 与旧配置的关系
+
+`tools.svgr` 取代了下面两个已废弃的配置项，二者目前仍然生效，并将在下一个大版本中移除：
+
+| 旧配置                                 | 新配置                                                   |
+| -------------------------------------- | -------------------------------------------------------- |
+| `output.svgDefaultExport: 'component'` | `tools.svgr: { svgrOptions: { exportType: 'default' } }` |
+| `output.svgDefaultExport: 'url'`       | `tools.svgr: { svgrOptions: { exportType: 'named' } }`   |
+| `output.disableSvgr: true`             | `tools.svgr: false`                                      |
+| `output.disableSvgr: false`            | 默认行为，直接删除即可                                   |
+
+同时设置时以 `tools.svgr` 为准：显式设置了 `tools.svgr` 后，`output.disableSvgr` 不再生效；`tools.svgr.svgrOptions.exportType` 会覆盖 `output.svgDefaultExport` 派生的值。

package/docs/zh/configure/app/usage.mdx

@@ -265,11 +265,7 @@ import { defineConfig } from '@modern-js/app-tools';
 import { xxPlugin } from '@modern-js/plugin-xx';
 
 export default defineConfig({
-  plugins: [
-    xxPlugin({
-      /** 在此处添加参数 */
-    }),
-  ],
+  plugins: [xxPlugin({/** 在此处添加参数 */})],
 });
 ```
 

package/docs/zh/guides/advanced-features/bff.mdx

@@ -1,6 +1,7 @@
 ---
 title: BFF
 ---
+
 # BFF
 
 BFF（Backends for Frontends）是一种架构模式，主要用于解决前后端协作中的数据聚合问题。在 BFF 架构下，前端应用程序不直接与后端服务通信，而是通过一个专门为前端定制的BFF中间层与后端服务交互。

package/docs/zh/guides/advanced-features/international/advanced.mdx

@@ -68,7 +68,7 @@ i18nPlugin({
     localeDetectionByEntry: {
       admin: {
         localePathRedirect: false, // admin 入口不使用路径前缀
-        languages: ['en'],         // admin 只支持英文
+        languages: ['en'], // admin 只支持英文
       },
       mobile: {
         languages: ['zh', 'en', 'ja'], // mobile 支持更多语言

package/docs/zh/guides/advanced-features/international/api.mdx

@@ -10,14 +10,14 @@ title: API 参考
 
 ### 返回值
 
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `language` | `string` | 当前语言代码 |
-| `changeLanguage` | `(lang: string) => Promise<void>` | 切换语言 |
-| `supportedLanguages` | `string[]` | 支持的语言列表（来自 `localeDetection.languages`） |
-| `isLanguageSupported` | `(lang: string) => boolean` | 检查语言是否在支持列表中 |
-| `isResourcesReady` | `boolean` | 当前语言的翻译资源是否已加载完成 |
-| `i18nInstance` | `I18nInstance` | i18next 实例（用于高级场景） |
+| 字段                  | 类型                              | 说明                                               |
+| --------------------- | --------------------------------- | -------------------------------------------------- |
+| `language`            | `string`                          | 当前语言代码                                       |
+| `changeLanguage`      | `(lang: string) => Promise<void>` | 切换语言                                           |
+| `supportedLanguages`  | `string[]`                        | 支持的语言列表（来自 `localeDetection.languages`） |
+| `isLanguageSupported` | `(lang: string) => boolean`       | 检查语言是否在支持列表中                           |
+| `isResourcesReady`    | `boolean`                         | 当前语言的翻译资源是否已加载完成                   |
+| `i18nInstance`        | `I18nInstance`                    | i18next 实例（用于高级场景）                       |
 
 ### 基本用法
 
@@ -85,13 +85,13 @@ function MyComponent() {
 
 ### Props
 
-| Prop | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `to` | `string` | 是 | 目标路径，不需要包含语言前缀 |
-| `children` | `React.ReactNode` | 是 | 链接内容 |
-| `replace` | `boolean` | 否 | 使用 `history.replace` 而非 `push` |
-| `state` | `any` | 否 | 传递给目标路由的状态 |
-| 其他 Link props | — | 否 | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
+| Prop            | 类型              | 必填 | 说明                                              |
+| --------------- | ----------------- | ---- | ------------------------------------------------- |
+| `to`            | `string`          | 是   | 目标路径，不需要包含语言前缀                      |
+| `children`      | `React.ReactNode` | 是   | 链接内容                                          |
+| `replace`       | `boolean`         | 否   | 使用 `history.replace` 而非 `push`                |
+| `state`         | `any`             | 否   | 传递给目标路由的状态                              |
+| 其他 Link props | —                 | 否   | 继承自 `@modern-js/runtime/router` 的 `Link` 组件 |
 
 ### 用法
 
@@ -132,6 +132,7 @@ const myPlugin = (): RuntimePlugin => ({
 ```
 
 **注意事项：**
+
 - 确保 i18n 插件在使用 `context.changeLanguage` 的插件之前注册
 - `changeLanguage` 在服务端不会更新 URL 路径，需要配合路由插件或手动处理
 
@@ -165,11 +166,11 @@ interface I18nInstance {
 type I18nSdkLoader = (options: I18nSdkLoadOptions) => Promise<Resources>;
 
 interface I18nSdkLoadOptions {
-  lng?: string;      // 单个语言代码
-  ns?: string;       // 单个命名空间
-  lngs?: string[];   // 多个语言代码
-  nss?: string[];    // 多个命名空间
-  all?: boolean;     // 加载所有资源
+  lng?: string; // 单个语言代码
+  ns?: string; // 单个命名空间
+  lngs?: string[]; // 多个语言代码
+  nss?: string[]; // 多个命名空间
+  all?: boolean; // 加载所有资源
 }
 
 type Resources = {
@@ -184,14 +185,14 @@ type Resources = {
 ```ts
 interface LanguageDetectorOptions {
   order?: string[];
-  lookupQuerystring?: string;   // 默认 'lng'
-  lookupCookie?: string;        // 默认 'i18next'
-  lookupLocalStorage?: string;  // 默认 'i18nextLng'
+  lookupQuerystring?: string; // 默认 'lng'
+  lookupCookie?: string; // 默认 'i18next'
+  lookupLocalStorage?: string; // 默认 'i18nextLng'
   lookupSession?: string;
-  lookupHeader?: string;        // 默认 'accept-language'
+  lookupHeader?: string; // 默认 'accept-language'
   lookupFromPathIndex?: number; // 默认 0
   caches?: false | string[];
-  cookieMinutes?: number;       // 默认 525600（1年）
+  cookieMinutes?: number; // 默认 525600（1年）
   cookieExpirationDate?: Date;
   cookieDomain?: string;
 }
@@ -211,8 +212,8 @@ import { useTranslation } from 'react-i18next';
 import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
 
 function App() {
-  const { t } = useTranslation();                          // 翻译文本
-  const { language, changeLanguage } = useModernI18n();    // 语言切换
+  const { t } = useTranslation(); // 翻译文本
+  const { language, changeLanguage } = useModernI18n(); // 语言切换
 
   return (
     <div>

package/docs/zh/guides/advanced-features/international/best-practices.mdx

@@ -63,8 +63,8 @@ function ButtonGroup() {
   const { t } = useTranslation('common', { keyPrefix: 'button' });
   return (
     <>
-      <button>{t('submit')}</button>   {/* → common:button.submit */}
-      <button>{t('cancel')}</button>   {/* → common:button.cancel */}
+      <button>{t('submit')}</button> {/* → common:button.submit */}
+      <button>{t('cancel')}</button> {/* → common:button.cancel */}
     </>
   );
 }
@@ -94,9 +94,9 @@ function ButtonGroup() {
 ```
 
 ```tsx
-t('page.title')
-t('form.username.label')
-t('form.submit', { defaultValue: '保存' }) // defaultValue 防止键缺失时显示 key 字符串
+t('page.title');
+t('form.username.label');
+t('form.submit', { defaultValue: '保存' }); // defaultValue 防止键缺失时显示 key 字符串
 ```
 
 ## 复数
@@ -121,9 +121,9 @@ i18next 根据 `count` 参数自动选择对应的复数形式。**注意：i18n
 ```
 
 ```tsx
-t('item', { count: 0 })  // → "没有条目" / "No items"
-t('item', { count: 1 })  // → "没有条目" / "1 item"（中文通常只有一种形式）
-t('item', { count: 5 })  // → "5 个条目" / "5 items"
+t('item', { count: 0 }); // → "没有条目" / "No items"
+t('item', { count: 1 }); // → "没有条目" / "1 item"（中文通常只有一种形式）
+t('item', { count: 5 }); // → "5 个条目" / "5 items"
 ```
 
 不同语言的复数规则不同（英语有单复数，俄语有 one/few/many 等多种形式），i18next 会根据语言代码自动匹配 CLDR 规则。
@@ -152,8 +152,8 @@ t('item', { count: 5 })  // → "5 个条目" / "5 items"
 ```
 
 ```tsx
-t('modal.confirm.title')
-t('modal.confirm.actions.ok')
+t('modal.confirm.title');
+t('modal.confirm.actions.ok');
 ```
 
 嵌套层级不建议超过 4 层，过深的结构会让键名变得冗长难维护。
@@ -199,8 +199,8 @@ export default defineRuntimeConfig({
 ```
 
 ```tsx
-t('price', { value: 99.5 })       // → "当前价格：¥99.50"（zh）/ "$99.50"（en）
-t('expiry', { date: new Date() }) // → "到期日：2025年5月12日"（zh）
+t('price', { value: 99.5 }); // → "当前价格：¥99.50"（zh）/ "$99.50"（en）
+t('expiry', { date: new Date() }); // → "到期日：2025年5月12日"（zh）
 ```
 
 ## 错误处理
@@ -237,7 +237,7 @@ if (!i18n.isInitialized) return null;
 通过 `defaultValue` 提供兜底文案，防止界面显示 key 字符串：
 
 ```tsx
-t('missing.key', { defaultValue: '默认文案' })
+t('missing.key', { defaultValue: '默认文案' });
 ```
 
 开发环境可以开启 `saveMissing`，将缺失的键输出到控制台方便排查：
@@ -281,8 +281,8 @@ declare module 'react-i18next' {
 
 ```tsx
 const { t } = useTranslation();
-t('welcome');       // ✅ TypeScript 自动补全
-t('nonExistent');   // ❌ TypeScript 报错
+t('welcome'); // ✅ TypeScript 自动补全
+t('nonExistent'); // ❌ TypeScript 报错
 ```
 
 :::tip 大型项目