@modern-js/main-doc 2.2.0 → 2.4.0

package/zh/configure/app/tools/inspector.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.inspector
 sidebar_label: inspector
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.inspector](https://modernjs.dev/builder/api/config-tools.html#tools-inspector)。
+# tools.inspector
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.inspector](https://modernjs.dev/builder/api/config-tools.html#toolsinspector)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/inspector.md'

package/zh/configure/app/tools/jest.mdx

@@ -5,8 +5,8 @@ sidebar_label: jest
 ---
 # jest
 
-- 类型： `Object | Function`
-- 默认值：`{}`
+- **类型：** `Object | Function`
+- **默认值：** `{}`
 
 :::caution 注意
 需要先通过 `pnpm run new` 启用 单元测试 功能。

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

@@ -1,10 +1,11 @@
 ---
-title: tools.less
 sidebar_label: less
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.less](https://modernjs.dev/builder/api/config-tools.html#tools-less)。
+# tools.less
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.less](https://modernjs.dev/builder/api/config-tools.html#toolsless)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/less.md'

package/zh/configure/app/tools/minify-css.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.minifyCss
 sidebar_label: minifyCss
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.minifyCss](https://modernjs.dev/builder/api/config-tools.html#tools-minifycss)。
+# tools.minifyCss
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.minifyCss](https://modernjs.dev/builder/api/config-tools.html#toolsminifycss)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/minifyCss.md'

package/zh/configure/app/tools/postcss.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.postcss
 sidebar_label: postcss
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.postcss](https://modernjs.dev/builder/api/config-tools.html#tools-postcss)。
+# tools.postcss
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.postcss](https://modernjs.dev/builder/api/config-tools.html#toolspostcss)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/postcss.md'

package/zh/configure/app/tools/pug.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.pug
 sidebar_label: pug
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.pug](https://modernjs.dev/builder/api/config-tools.html#tools-pug)。
+# tools.pug
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.pug](https://modernjs.dev/builder/api/config-tools.html#toolspug)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/pug.md'

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

@@ -1,10 +1,11 @@
 ---
-title: tools.sass
 sidebar_label: sass
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.sass](https://modernjs.dev/builder/api/config-tools.html#tools-sass)。
+# tools.sass
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.sass](https://modernjs.dev/builder/api/config-tools.html#toolssass)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/sass.md'

package/zh/configure/app/tools/style-loader.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.styleLoader
 sidebar_label: styleLoader
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.styleLoader](https://modernjs.dev/builder/api/config-tools.html#tools-styleloader)。
+# tools.styleLoader
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.styleLoader](https://modernjs.dev/builder/api/config-tools.html#toolsstyleloader)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/styleLoader.md'

package/zh/configure/app/tools/styled-components.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.styledComponents
 sidebar_label: styledComponents
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.styledComponents](https://modernjs.dev/builder/api/config-tools.html#tools-styledcomponents)。
+# tools.styledComponents
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.styledComponents](https://modernjs.dev/builder/api/config-tools.html#toolsstyledcomponents)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/styledComponents.md'

package/zh/configure/app/tools/swc.mdx

@@ -4,8 +4,8 @@ sidebar_label: swc
 ---
 # swc
 
-- 类型： `Object`
-- 默认值： `undefined`
+- **类型：** `Object`
+- **默认值：** `undefined`
 
 ## 介绍
 

package/zh/configure/app/tools/tailwindcss.mdx

@@ -1,15 +1,11 @@
 ---
-title: tools.tailwindcss
-
 sidebar_label: tailwindcss
 ---
-# tailwindcss
 
-- 类型： `Object | Function`
-- 默认值：见下方配置详情。
+# tools.tailwindcss
 
-<details>
-  <summary>TailwindCSS 配置详情</summary>
+- **类型：** `Object | Function`
+- **默认值：**
 
 ```js
 const tailwind = {
@@ -23,21 +19,19 @@ const tailwind = {
     './src/**/*.tsx',
     './storybook/**/*',
   ],
-  theme: source.designSystem, // 使用source.designSystem配置作为Tailwind CSS Theme配置
+  // 使用 source.designSystem 配置作为 Tailwind CSS Theme 配置
+  theme: source.designSystem,
 };
 ```
 
-:::tip 提示
-更多关于：<a href="https://tailwindcss.com/docs/configuration" target="_blank">TailwindCSS 配置</a>。
-
-:::
+对应 [TailwindCSS](https://tailwindcss.com/docs/configuration) 的配置。
 
-</details>
+当值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。
 
-对应 [TailwindCSS](https://tailwindcss.com/docs/configuration) 的配置，值为 `Object` 类型时，与默认配置通过 `Object.assign` 合并。
+当值为 `Function` 类型时，函数返回的对象与默认配置通过 `Object.assign` 合并。
 
-值为 `Function` 类型时，函数返回的对象与默认配置通过 `Object.assign` 合并。
+### 限制
 
-不允许出现 `theme` 属性，否则会构建失败。 Modern.js 使用 [`source.designSystem`](/configure/app/source/design-system) 作为 `Tailwind CSS Theme` 配置。
+注意，该配置中不允许使用 `theme` 配置项，否则会构建失败。在 Modern.js 中，请使用 [source.designSystem](/configure/app/source/design-system) 作为 `Tailwind CSS Theme` 配置。
 
 其他的使用方式和 Tailwind CSS 一致: [快速传送门](https://tailwindcss.com/docs/configuration)。

package/zh/configure/app/tools/terser.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.terser
 sidebar_label: terser
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.terser](https://modernjs.dev/builder/api/config-tools.html#tools-terser)。
+# tools.terser
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.terser](https://modernjs.dev/builder/api/config-tools.html#toolsterser)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/terser.md'

package/zh/configure/app/tools/ts-checker.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.tsChecker
 sidebar_label: tsChecker
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.tsChecker](https://modernjs.dev/builder/api/config-tools.html#tools-tschecker)。
+# tools.tsChecker
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.tsChecker](https://modernjs.dev/builder/api/config-tools.html#toolstschecker)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/tsChecker.md'

package/zh/configure/app/tools/ts-loader.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.tsLoader
 sidebar_label: tsLoader
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.tsLoader](https://modernjs.dev/builder/api/config-tools.html#tools-tsloader)。
+# tools.tsLoader
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.tsLoader](https://modernjs.dev/builder/api/config-tools.html#toolstsloader)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/tsLoader.md'

package/zh/configure/app/tools/webpack-chain.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.webpackChain
 sidebar_label: webpackChain
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.webpackChain](https://modernjs.dev/builder/api/config-tools.html#tools-webpackchain)。
+# tools.webpackChain
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.webpackChain](https://modernjs.dev/builder/api/config-tools.html#toolswebpackchain)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpackChain.md'

package/zh/configure/app/tools/webpack.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.webpack
 sidebar_label: webpack
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.webpack](https://modernjs.dev/builder/api/config-tools.html#tools-webpack)。
+# tools.webpack
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.webpack](https://modernjs.dev/builder/api/config-tools.html#toolswebpack)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpack.md'

package/zh/configure/app/usage.mdx

@@ -8,22 +8,22 @@ Modern.js 中有两种配置，一个是编译时配置，一个是服务端运
 
 编译时配置可以在两个位置进行配置：
 
+- 根路径下的 `modern.config.(ts|js|mjs)` 文件
 - `package.json` 文件
-- 根路径下的 `modern.config.t(j)s` 文件
-
-:::warning 注意
-同一个配置不支持同时在 `package.json` 中和 `modern.config.t(j)s` 中配置。推荐在 `modern.config.t(j)s` 中进行配置。
 
+:::info
+不支持同时在 package.json 中和 modern.config.ts 中配置同一个配置项，推荐优先在 modern.config.ts 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
 :::
 
-服务端运行时配置可以在根路径下的 `modern.server-runtime.config.t(j)s` 自定义配置选项。
+服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中自定义配置选项。
 
 ## 在配置文件中配置
 
-Modern.js 的配置文件定义在项目的根目录下，同时支持 `.js` 和 `.ts` 两种格式：
+Modern.js 的配置文件定义在项目的根目录下，支持 `.js`, `.ts` 和 `.mjs` 格式：
 
 - `modern.config.js`
 - `modern.config.ts`
+- `modern.config.mjs`
 
 ### modern.config.js
 
@@ -51,7 +51,7 @@ export default {
 };
 ```
 
-### modern.config.ts
+### modern.config.ts（推荐）
 
 我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
 
@@ -69,6 +69,69 @@ export default defineConfig({
 });
 ```
 
+### 导出配置函数
+
+Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(({ env, command }) => ({
+  source: {
+    alias: {
+      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
+    },
+  },
+}));
+```
+
+该函数接受以下入参：
+
+- `env`：对应 `process.env.NODE_ENV` 的值。
+  - 当运行 `modern dev` 或 `modern start` 时，`env` 的值为 `development`。
+  - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
+  - 当运行 `modern test` 时，`env` 的值为 `test`。
+- `command`: 对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
+
+### 导出异步函数
+
+Modern.js 也支持在配置文件中导出一个异步函数，你可以在函数中进行一些异步操作：
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(async ({ env, command }) => {
+  const result = await someAsyncFunction();
+
+  return {
+    html: {
+      title: result,
+    },
+  };
+});
+```
+
+### 指定配置文件
+
+Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称。
+
+例如，你需要在执行 build 命令时使用 `modern.prod.config.ts` 文件，可以在 `package.json` 中添加如下配置：
+
+```json title="package.json"
+{
+  "scripts": {
+    "dev": "modern modern",
+    "build": "modern build --config modern.prod.config.ts"
+  }
+}
+```
+
+你也可以将 `--config` 选项缩写为 `-c`：
+
+```bash
+$ modern build -c modern.prod.config.js
+```
+
 ## 在 package.json 中配置（不推荐）
 
 除了配置文件外，也可以在 `package.json` 中的 `modernConfig` 字段下设置配置选项，如：
@@ -87,7 +150,53 @@ export default defineConfig({
 
 由于 JSON 文件格式的限制，`package.json` 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。
 
-## 注意事项
+### 注意事项
 
 - 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示。
 - `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
+
+## 本地调试配置
+
+为了便于本地调试配置，Modern.js 支持在项目根目录下创建 `modern.config.local.(ts|js|mjs)` 文件，用于覆盖 `modern.config.(ts|js|mjs)` 中的配置选项。
+
+### 示例
+
+比如，项目的 `modern.config.ts` 中配置了端口号为 `3000`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+如果你在本地调试时需要将端口号修改为 `3001`，但是又不希望修改当前项目的 `modern.config.ts` 文件，那么可以创建一个 `modern.config.local.ts` 文件，并添加以下配置：
+
+```ts title="modern.config.local.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+`modern.config.local.ts` 文件中的配置会与 `modern.config.ts` 中的配置进行深层合并，并覆盖 `modern.config.ts` 中的配置选项，因此 `server.port` 会被覆盖为 `3001`。
+
+### 注意事项
+
+在使用 `modern.config.local.ts` 时，请注意以下事项：
+
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 或 `modern start` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
+- 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
+
+```bash title=".gitingore"
+modern.config.local.ts
+modern.config.local.js
+modern.config.local.mjs
+```

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

@@ -41,7 +41,7 @@ export default () => {
 };
 ```
 
-:::info 注
+:::info
 Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可以直接通过别名的方式引入函数。
 
 :::
@@ -102,7 +102,7 @@ Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，
 
 Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义, 遵循 HTTP Method 规范，并且不允许自由定义参数。
 
-:::info 注
+:::info
 假设函数允许自由定义参数，产出的路由必然由**私有协议**进行调用（原因是无法区分请求参数与请求体），而无法实现任意的 RESTful API。
 
 如果服务仅用于应用本身不存在问题，但它**不标准的接口定义**无法融入更大的体系。 在多个系统共同工作的情况下（例如 BFF 低码搭建），会导致其他系统也需要遵循**私有协议**。
@@ -141,7 +141,7 @@ export const post = async () => {
 
 - 可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
 
-:::info 注
+:::info
 需要注意的是，定义的函数都应该是异步的，与函数调用时类型有关，后面会提到。
 
 :::

package/zh/guides/advanced-features/code-split.mdx

@@ -74,7 +74,7 @@ function MyComponent() {
 
 `loadable` 更多用法请见 [loadable API](/apis/app/runtime/utility/loadable)。
 
-:::info 注
+:::info
 `loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
 
 :::

package/zh/guides/advanced-features/compatibility.mdx

@@ -31,7 +31,7 @@ Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js
 
 默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
 
-:::info 注
+:::info
 对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
 
 :::

package/zh/guides/advanced-features/eslint.mdx

@@ -16,7 +16,7 @@ sidebar_position: 8
 
 多数问题会被 ESLint 规则的自动修复功能或 [Prettier](https://prettier.io/) 的代码格式化功能（已被集成到 ESLint 里）自动解决，开发者不需要关心问题的细节和解决方式。
 
-:::info 注
+:::info
 主要在 IDE 保存文件的环节执行这种自动修复，少数漏网之鱼会在提交代码环节被自动修复。
 
 :::
@@ -45,7 +45,7 @@ pnpm run lint:error
 /* eslint-enable filenames/match-exported */
 ```
 
-:::info 注
+:::info
 在 VS Code 编辑器里输入 eslint，会自动出现关于 "eslint-disable" 的提示框，选择提示选项生成对应注释对。
 
 :::
@@ -76,7 +76,7 @@ pnpm run lint:error
 
 Modern.js 的应用工程、模块工程，源代码目录里都会默认有这个配置文件，是针对 Universal JS 代码设计的。
 
-:::info 注
+:::info
 Universal JS 代码是既能浏览器端也能在服务器端运行的代码。
 
 :::

package/zh/guides/advanced-features/ssr.mdx

@@ -66,7 +66,7 @@ Warning: Expected server HTML to contain a matching <div> in <div>.
 
 这是 React 在客户端执行 hydrate 逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
 
-:::info 注
+:::info
 关于 hydrate (注水)逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
 
 :::
@@ -242,11 +242,11 @@ if (process.env.MODERN_TARGET === 'browser') {
 例如在代码中引入了 `fs-extra`，这时候直接引用到组件中，会造成 CSR 加载报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
 
 ```ts title="compat.ts"
-export { readFileSync } from 'fs-extra';
+export const readFileSync: any = () => {};
 ```
 
 ```ts title="compat.node.ts"
-export const readFileSync: any = () => {};
+export { readFileSync } from 'fs-extra';
 ```
 
 在文件中直接引入 `./compat`，此时 SSR 环境下会优先使用 `.node.ts` 后缀的文件，CSR 环境下会使用 `.ts` 后缀的文件。

package/zh/guides/basic-features/alias.mdx

@@ -13,7 +13,7 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 }
 ```
 
-:::info 注
+:::info
 在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名。
 
 :::

package/zh/guides/basic-features/builder.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 **Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
 
-Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向现代 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 Rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
 
 ## 构建架构
 
@@ -14,7 +14,7 @@ Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向
 
 - 上层研发框架：Modern.js。
 - 通用构建引擎：Modern.js Builder。
-- 底层打包工具：webpack 和 rspack。
+- 底层打包工具：webpack 和 Rspack。
 
 <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
 

package/zh/guides/basic-features/css/postcss.mdx

@@ -10,7 +10,7 @@ sidebar_position: 3
 
 1. [Autoprefixer](https://github.com/postcss/autoprefixer) 根据需要支持的浏览器范围，会自动为 CSS 规则添加需要的浏览器厂商前缀。Modern.js 默认支持的浏览器范围为：`['> 0.01%', 'not dead', 'not op_mini all']`。
 
-:::info 注意
+:::info意
   - 【支持的浏览器范围为：`> 0.01%`】是指浏览器市场份额大于 0.01%。
   - `not dead` 是指不包含官方不再支持的浏览器和过去24个月没有更新的浏览器。
   - `not op_mini all` 是指不包含 Opera Mini。

package/zh/guides/basic-features/html.mdx

@@ -217,7 +217,7 @@ Modern.js 也支持 HTML 语法。默认情况下，Modern.js 的应用工程中
 
 在 `config/html/` 目录下，创建 `index.html` 文件,该文件将替代默认的 HTML 模板。
 
-:::info 注
+:::info
 内部默认 HTML 模板可以在 `node_modules/.modern-js/${entryName}/index.html` 中查看。
 
 :::

package/zh/guides/basic-features/routes.mdx

@@ -4,7 +4,7 @@ sidebar_position: 1
 ---
 # 路由
 
-Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**部分**支持，并提供了多种类型的路由模式。根据不同[入口](/guides/concept/entries)类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**其他路由方案**。
+Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，并提供了多种类型的路由模式。根据不同[入口](/docs/guides/concept/entries)类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**其他路由方案**。
 
 :::note
 本小节提到的路由，都是客户端路由，即 SPA 路由。
@@ -168,6 +168,33 @@ export default () => {
 
 在 loader 中，params 会作为 [loader](/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
 
+### 通配路由
+
+如果在 routes 目录下创建 `$.tsx` 文件，该文件会作为通配路由组件，当没有匹配的路由时，会渲染该路由组件。
+
+:::note
+`$.tsx` 可以认为是一种特殊的 `page` 路由组件，当前目录下有 `layout` 组件时，`$.tsx`，会作为 `layout` 的子组件渲染。
+:::
+
+例如以下目录结构：
+```
+└── routes
+    ├── $.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+当访问任何匹配不到的路径时，都会渲染 `routes/$.tsx` 组件，同样，`$.tsx` 中可以使用 [useParams](/apis/app/runtime/router/#useparams) 捕获 url 的剩余部分。
+```ts title="$.tsx"
+import { useParams } from '@modern-js/runtime/router';
+// 当 path 是 `/aaa/bbb` 时
+const params = useParams();
+params['*']  // => 'aaa/bbb'
+```
+
+`$.tsx` 可以加入到 `routes` 目录下的任意目录中，一个常见的使用示例是添加 `routes/$.tsx` 文件去定制任意层级的 404 页面。
+
 ### 无路径布局
 
 当目录名以 \_\_ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：

package/zh/guides/topic-detail/framework-plugin/hook.mdx

@@ -76,7 +76,7 @@ pipeline.run(5); // 6
 
 上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
 
-:::info 注
+:::info
 当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
 
 ```ts

package/zh/guides/topic-detail/generator/config/{mwa.mdx → app.mdx}

@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# 应用
+# Web 应用
 
 ## 项目创建