@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -0,0 +1,152 @@
+---
+title: ESLint 规则集
+sidebar_position: 8
+---
+# ESLint 规则集
+
+{/* 参考 [实战教程 - 确认编程环境](../handbook/c03-ide/3.1-setting-up) 确保本地 IDE 环境正常。  */}
+
+**Modern.js ESLint 规则集**是全量的 **ESLint** 规则集合，包含 `@modern-js` （对于 Node.js 项目的 Lint 规则）和 `@modern-js-app`（对于前端项目的 Lint 规则）。
+
+下面以具体问题介绍更多 ESLint 用法。
+
+## Q: 如何处理 Lint
+
+### 实时自动修复
+
+多数问题会被 ESLint 规则的自动修复功能或 [Prettier](https://prettier.io/) 的代码格式化功能（已被集成到 ESLint 里）自动解决，开发者不需要关心问题的细节和解决方式。
+
+:::info 注
+主要在 IDE 保存文件的环节执行这种自动修复，少数漏网之鱼会在提交代码环节被自动修复。
+
+:::
+
+### 批量自动修复
+
+在少数情况下，比如旧项目迁移的时候，可以执行以下命令，批量修复和检查所有文件：
+
+```bash
+pnpm run lint:error
+```
+
+### 人工修复
+
+对于无法自动修复的问题，可以在 IDE 里点击问题提示框里的规则链接，打开这条规则的文档，查看问题的解释和解决方案。
+
+### 声明例外情况
+
+目前阶段，有些规则并不能做到足够智能，多数情况下会有很大收益，在少数情况下也许不适用。但如果为了这些少数情况就把整个规则关掉或改掉，得不偿失。
+
+这种情况下可以用 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 注释，对符合**少数情况**的代码块做标注，声明这里是一个例外，应该忽略。比如：
+
+```js
+/* eslint-disable filenames/match-exported */
+...
+/* eslint-enable filenames/match-exported */
+```
+
+:::info 注
+在 VS Code 编辑器里输入 eslint，会自动出现关于 "eslint-disable" 的提示框，选择提示选项生成对应注释对。
+
+:::
+
+【Modern.js ESLint 规则集】要求 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 必须成对使用，必须明确表达要影响的范围，以及在这个范围内明确表达要禁用什么规则，目的是让**例外**有明确的、最小化的范围，避免 [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) 被滥用，导致不属于例外的代码也被禁用了规则。
+
+## Q: 如何自定义 ESLint 规则
+
+### 仓库根目录下 `package.json` 里的 "eslintConfig" 字段
+
+这个地方是整个仓库的默认 ESLint 配置，是针对纯 Node.js 代码（只能在 Node.js 里运行）设计的。
+
+如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置。该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
+
+```json
+ "eslintConfig": {
+    "extends": [
+      "@modern-js"
+    ],
+    "rules": {
+      "filenames/match-exported": "off"
+    }
+  },
+
+```
+
+### `src/.eslintrc.js` 文件
+
+Modern.js 的应用工程、模块工程，源代码目录里都会默认有这个配置文件，是针对 Universal JS 代码设计的。
+
+:::info 注
+Universal JS 代码是既能浏览器端也能在服务器端运行的代码。
+
+:::
+
+如果项目在某些规则上确实有特殊要求或不可避免的兼容问题（不是例外），可以在这里增加规则配置，该配置会优先于默认的【Modern.js ESLint 规则集】，比如：
+
+```js
+// eslint-disable-next-line import/no-commonjs
+module.exports = {
+  root: true,
+  extends: ['@modern-js-app'],
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['../tsconfig.json'],
+  },
+  rules: {
+    'filenames/match-exported': 'off',
+  },
+};
+```
+
+如果有需要，还可以继续在不同的子目录里增加 `.eslintrc.js` 文件，针对这个子目录里的代码做特殊配置：
+
+```js
+module.exports = {
+  rules: {
+    'filenames/match-exported': 'off',
+  },
+};
+```
+
+:::tip 提示
+注意：没有必要使用 `extends` 字段，会自动继承父目录的配置。
+
+:::
+
+### package.json 里的 `eslintIgnore` 字段
+
+把包含 `.js`、`.jsx`、`.ts`、`.tsx` 文件、但不需要做代码检查和自动修复的目录，添加到 `eslintIgnore` 里，可以优化 ESLint 检查的速度，比如：
+
+```json
+ "eslintIgnore": [
+    "node_modules",
+    "dist",
+    "output"
+  ],
+```
+
+## Q: 如何升级 ESLint 插件的版本
+
+只要不是 Major 版本的变化（不符合 [Semver](https://semver.org/) 规则的 `^` 符号），就可以直接在业务项目的 `package.json` 里指定这个依赖，删除 Lock 文件（或尝试手动删除 Lock 文件中这个包名的内容），执行 `pnpm install` 重新安装依赖并且生成新的 Lock 文件。
+
+做完这些操作之后，在业务项目的 `./node_modules` 目录里，这个插件应该只存在一份，并且升级到了你指定的版本。
+
+:::tip 提示
+- Major 版本就是主版本号。更多信息，请阅读【[Semantic Versioning](https://semver.org/#summary)】。
+- 所有被 Modern.js 封装的上游项目（比如 ESLint、[ESLint 插件](https://eslint.org/docs/user-guide/configuring/plugins#plugins)、[React Router](https://reactrouter.com/) 等），也都可以这样升级。
+- Modern.js 也会在每次发版中尽量及时的升级这些上游依赖。
+- Major 版本的升级需要由 Modern.js 来发版。
+
+:::
+
+## Q: WebStorm 有时候会报 ESLint 错误
+
+由于 WebStorm 认为 ESLint 执行目录是根据 `.eslintrc` 文件来决定的。因此 `src/.eslintrc` 文件位置的放置会导致 `tsconfig.json` 文件指定的位置（项目根目录下）在 `src/` 目录下找不到。
+
+此时需要手动配置一下：
+
+```json
+--parser-options=project:../tsconfig.json
+```
+
+![webstorm-lint-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/webstorm-lint-error.png)

package/zh/guides/advanced-features/low-level.mdx

@@ -0,0 +1,43 @@
+---
+title: 配置底层工具
+sidebar_position: 11
+---
+# 配置底层工具
+
+## 使用方式
+
+Modern.js 内部默认集成了 [Babel](https://babeljs.io/)、[TypeScript](https://www.typescriptlang.org/)、[Webpack](https://webpack.js.org/)、[PostCSS](https://postcss.org/)、[Tailwind CSS](https://tailwindcss.com/) 等工具。通常情况下，默认配置能够满足大多业务开发需求。当有特殊需求时，可以通过底层配置来实现。
+
+以配置 Webpack 为例，只需要在 `modern.config.ts` 中添加 [`tools.webpack`](/configure/app/tools/webpack) 即可：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  tools: {
+    webpack: config => {},
+  },
+});
+```
+
+`tools` 命名空间下的配置都可以设置为 `Object` 或者 `Function`。
+
+值为 `Object` 时，会与内部默认配置进行合并，具体合并策略参考对应的配置选项文档（见下表）。
+
+值为 `Function` 时，第一个参数为内部的默认配置对象，可以直接修改这个对象不做返回，也可以返回一个新的对象或者合并后的对象作为最终结果。
+
+## 底层配置明细
+
+目前提供的底层配置如下表：
+
+| 底层工具          | 配置                                                                  |
+| ----------------- | --------------------------------------------------------------------- |
+| DevServer         | [tools.devServer](/configure/app/tools/dev-server)               |
+| Babel             | [tools.babel](/configure/app/tools/babel)                        |
+| styled-components | [tools.styledComponents](/configure/app/tools/styled-components) |
+| PostCSS           | [tools.postcss](/configure/app/tools/postcss)                    |
+| Less              | [tools.less](/configure/app/tools/less)                          |
+| Sass              | [tools.sass](/configure/app/tools/sass)                          |
+| webpack           | [tools.webpack](/configure/app/tools/webpack)                    |
+| Minify CSS        | [tools.minifyCss](/configure/app/tools/minify-css)               |
+| terser            | [tools.terser](/configure/app/tools/terser)                      |
+| Tailwind CSS      | [tools.tailwind](/configure/app/tools/tailwindcss)               |
+| Autoprefixer      | [tools.autoprefixer](/configure/app/tools/autoprefixer)          |

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

@@ -0,0 +1,117 @@
+---
+title: 静态站点生成（SSG）
+sidebar_position: 4
+---
+# 静态站点生成（SSG）
+
+SSG（Static Site Generation）是一种基于数据与模板，在构建时渲染完整静态网页的技术解决方案。
+
+我们首先需要执行 `pnpm run new` 启用 SSG 功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「SSG」功能
+```
+
+执行命令后，在 `modern.config.ts` 中注册 SSG 插件：
+
+```ts title="modern.config.ts"
+import ssgPlugin from '@modern-js/plugin-ssg';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+  plugins: [..., ssgPlugin()],
+});
+```
+
+SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
+
+### 在约定式路由中使用
+
+**约定式路由**中， Modern.js 根据入口下的文件结构生成路由，因此框架能够收集完整的路由信息。
+
+例如，以下是一个使用约定式路由的项目目录结构：
+
+```
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
+```
+
+上述文件目录将会生成以下三条路由：
+
+- `/`
+- `/user`
+- `/user/profile`
+
+:::note
+如果还不了解约定式路由的规则，可以先查看[路由](/guides/basic-features/routes)。
+
+:::
+
+在 `src/routes/page.tsx` 中添加组件代码：
+
+```jsx title="src/routes/page.tsx"
+export default () => {
+  return <div>Index Page</div>;
+};
+```
+
+SSG 也是在 Node.js 环境渲染页面，因此我们可以在**开发阶段开启 SSR**，提前在暴露代码问题，验证 SSG 渲染效果：
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  }
+}
+```
+
+在项目根路径下执行 `pnpm run dev` 命令，查看 `dist/` 目录，此时只生成一个 HTML 文件 `main/index.html`。
+
+在项目根路径下执行 `pnpm run build` 命令，构建完成后，查看 `dist/` 目录，此时生成 `main/index.html`、`main/user/index.html` 和 `main/user/profile/index.html` 三个 HTML 文件，内容分别对应上述三条路由。
+
+**约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `Index Page` 的文本内容，这正是 SSG 的效果。
+
+执行 `pnpm run serve` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
+
+### 在自控式路由中使用
+
+**自控式路由**是通过组件代码自定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。此时需要用户提前告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
+
+例如有以下代码，包含多条路由，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`：
+
+import SelfRouteExample from "@site-docs/components/self-route-example";
+
+<SelfRouteExample />
+
+如果我们希望同时开启 `/about` 的 SSG 功能，可以配置 `output.ssg`，告知 Modern.js 开启指定路由的 SSG 功能。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: ['/', '/about'],
+    },
+  },
+});
+```
+
+执行 `pnpm run build` 与 `pnpm run serve` 后，访问 `http://localhost:8080/about`，在 Preview 视图中可以看到页面已经完成渲染。
+
+查看构建产物文件，可以看到 `dist/` 目录中，新增了一个 `main/about/index.html` 文件。
+
+:::info
+以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/configure/app/output/ssg)。
+
+:::

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

@@ -0,0 +1,294 @@
+---
+title: 服务端渲染（SSR）
+sidebar_position: 3
+---
+# 服务端渲染（SSR）
+
+在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
+
+启用 SSR 非常简单，只需要设置 [`server.ssr`](/configure/app/server/ssr) 为 `true` 即可：
+
+```json
+{
+  "server": {
+    "ssr": true
+  }
+}
+```
+
+## SSR 时的数据获取
+
+Modern.js 中提供了 Data Loader，方便开发者在 SSR、CSR 下同构的获取数据。每个路由模块，如 `layout.tsx` 和 `page.tsx` 都可以定义自己的 Data Loader：
+
+```ts title="src/routes/page.tsx"
+export const loader = () => {
+  return {
+    message: 'Hello World',
+  };
+};
+```
+
+在组件中可以通过 Hooks API 的方式获取 `loader` 函数返回的数据：
+
+```tsx
+export default () => {
+  const data = useLoaderData();
+  return <div>{data.message}</div>;
+};
+```
+
+Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发体验。并且提供了优雅的降级处理，一旦 SSR 请求失败，会自动降级在浏览器端重新发起请求。
+
+不过，开发者仍然需要关注数据的兜底处理，例如 `null` 值或不符合预期的数据返回。避免在 SSR 时产生 React 渲染错误或是返回凌乱的渲染结果。
+
+:::info 补充信息
+使用 Data Loader 时，数据获取发生在渲染前，Modern.js 也仍然支持在组件渲染时获取数据。更多相关内容可以查看[数据获取](/guides/basic-features/data-fetch)。
+
+:::
+
+## 保持渲染一致
+
+有些业务中，通常需要根据当前的运行容器环境特征做不同的 UI 展示，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息。如果处理不够仔细，此时很有可能出现不符合预期的渲染结果。
+
+这里通过一个例子，演示当 SSR 与 CSR 渲染不一致时出现的问题，在组件中添加以下代码：
+
+```tsx
+{
+  typeof window !== 'undefined' ? <div>browser content</div> : null;
+}
+```
+
+启动应用后，访问页面，会发现浏览器控制台抛出警告信息：
+
+```sh
+Warning: Expected server HTML to contain a matching <div> in <div>.
+```
+
+这是 React 在客户端执行 hydrate 逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
+
+:::info 注
+关于 hydrate (注水)逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
+
+:::
+
+应用需要保持 SSR 与 CSR 渲染结果的一致性，如果存在不一致的情况，说明这部分内容无需在 SSR 中进行渲染。Modern.js 为这类在 SSR 中不需要渲染的内容提供 [`<NoSSR>` 工具组件](/apis/app/runtime/core/use-runtime-context)：
+
+```ts
+import { NoSSR } from '@modern-js/runtime/ssr';
+```
+
+在不需要进行 SSR 的元素外部，用 `NoSSR` 组件包裹：
+
+```tsx
+<NoSSR>
+  <div>client content</div>
+</NoSSR>
+```
+
+修改代码后，刷新页发现之前的 Waring 消失。打开浏览器开发者工具的 Network 窗口，查看返回的 HTML 文档是不包含 `NoSSR` 组件包裹的内容的。
+
+:::info 补充信息
+[`useRuntimeContext`](/apis/app/runtime/core/use-runtime-context) 可以获取完整的请求信息，可以利用它保证 SSR 与 CSR 的渲染结果一致。
+
+:::
+
+## 关注内存泄漏
+
+:::warning 警告
+在 SSR 场景下，开发者需要特别关注内存泄露问题，即使是微小的内存泄露，在大量的访问后也会对服务造成影响。
+
+:::
+
+SSR 时，浏览器的每次请求，都会触发服务端重新执行一次组件渲染逻辑。所以，需要避免在全局定义任何可能不断增长的数据结构，或在全局进行事件订阅，或创建不会被销毁的流。
+
+例如以下代码，使用 [redux-observable](https://redux-observable.js.org/) 时，习惯了 CSR 的开发者通常会在组件中这样编码：
+
+```tsx
+/* 代码仅作为示例，不可运行 */
+import { createEpicMiddleware, combineEpics } from 'redux-observable';
+
+const epicMiddleware = createEpicMiddleware();
+const rootEpic = combineEpics();
+
+export default function Test() {
+  epicMiddleware.run(rootEpic);
+  return <div>Hello Modern.js</div>;
+}
+```
+
+在组件外层创建 Middleware 实例 `epicMiddleware`，并在组件内部调用 `epicMiddleware.run`。
+
+在浏览器端，这段代码不会造成任何问题，但是在 SSR 时，Middleware 实例会一直无法被销毁。每次渲染组件，调用 `epicMiddleware.run(rootEpic)` 时，都会在内部添加新的事件绑定，导致整个对象不断变大，最终对应用性能造成影响。
+
+CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不确定应用是否存在这类隐患，可以对应用进行压测。
+
+## 收敛服务端数据
+
+为了保持 SSR 阶段请求的数据，可以在浏览器端直接使用，Modern.js 会将渲染过程中收集的数据与状态注入到 HTML 内。但是，CSR 应用常常存在接口数据量大、组件状态未收敛的情况，这时如果直接使用 SSR，渲染得到的 HTML 体积可能会存在过大的问题。此时，SSR 不仅无法为应用带来用户体验上的提升，反而可能起到相反的作用。
+
+因此，使用 SSR 时，**开发者需要为应用做合理的瘦身**：
+
+1. 关注首屏，SSR 中可以只请求首屏需要的数据，并在浏览器端渲染剩余的部分。
+2. 将与渲染无关的数据，从接口返回数据中剔除。
+
+## Serverless Pre-render
+
+Modern.js 提供 Serverless Pre-rendering (SPR) 这一特性来提升 SSR 性能。
+
+SPR 利用预渲染与缓存技术，为 SSR 页面提供静态 Web 的响应性能。它让 SSR 应用拥有静态 Web 页面的响应速度与稳定性，同时还能保持数据的动态更新。
+
+在 Modern.js 中使用 SPR 非常简单，只需要在组件中新增 `PreRender` 组件，该组件所在的页面就会自动开启 SPR。
+
+这里模拟一个使用 `useLoaderData` API 的组件，Data Loader 中的请求需要消耗 2s 时间。
+
+```jsx
+import { useLoaderData } from '@modern-js/runtime/router';
+
+export const loader = async () => {
+  await new Promise((resolve, reject) => {
+    setTimeout(() => {
+      resolve(null);
+    }, 2000);
+  });
+
+  return {
+    message: 'Hello Modern.js',
+  };
+};
+
+export default () => {
+  const data = useLoaderData();
+  return <div>{data?.message}</div>;
+};
+```
+
+执行 `dev` 命令后，打开页面，可以明显的察觉到页面需要等到 2s 后才返回。
+
+接下来使用 `PreRender` 组件来进行优化，该组件可以直接从 `@modern-js/runtime/ssr` 中导出：
+
+```ts
+import { PreRender } from '@modern-js/runtime/ssr';
+```
+
+在路由组件内使用 `PreRender` 组件，并设置参数 `interval`，用于表示该次渲染结果的过期时间为 5s：
+
+```tsx
+<PreRender interval={5} />
+```
+
+修改后，执行 `pnpm run build && pnpm run serve` 启动应用，并打开页面。
+
+首次打开时，和之前的渲染并没有什么不同，同样存在 2s 延迟。点击刷新，页面瞬间打开，但此时，页面数据并没有因为刷新发生变化，这是因为缓存还没有过期。
+
+等待 5s，重新刷新页面，页面的数据仍然没有变化。再一次刷新页面数据发生变化，但是页面仍然几乎是瞬间响应的。
+这是因为在之前的请求时，SPR 已经在后台异步获取了新的渲染结果，本次请求到的页面是已经缓存在服务器中的版本。
+
+可以想象，当 `interval` 设置为 1 时，用户可以在感知到实时数据的同时，拥有静态页面的响应体验。
+
+:::info 补充信息
+`PreRender` 的详细使用可以参考[这里](/apis/app/runtime/ssr/pre-render)。
+
+:::
+
+## Treeshaking
+
+开启 SSR 时，Modern.js 会用相同的入口，构建出 SSR Bundle 和 CSR Bundle 两份产物。因此，在 SSR Bundle 中存在 Web API，或是在 CSR Bundle 中存在 Node API 时，都可能导致运行出错。
+
+在组件中引入 Web API，通常情况下是要做一些全局监听，或是获取浏览器相关的数据，例如：
+
+```tsx
+document.addEventListener('load', () => {
+  console.log('document load');
+});
+const App = () => {
+  return <div>Hello World</div>;
+};
+export default App;
+```
+
+在组件文件中引入 Node API，通常情况下是因为使用了 Data Loader，例如：
+
+```ts
+import fse from 'fs-extra';
+export const loader = () => {
+  const file = fse.readFileSync('./myfile');
+  return {
+    ...
+  };
+};
+```
+
+### 环境变量区分
+
+对于第一种情况，我们可以直接使用 Modern.js 内置的环境变量 `MODERN_TARGET` 进行判断，在构建时删除无用代码：
+
+```ts
+if (process.env.MODERN_TARGET === 'browser') {
+  document.addEventListener('load', () => {
+    console.log('document load');
+  });
+}
+```
+
+:::note
+更多内容可以查看[环境变量](/guides/basic-features/env-vars)。
+
+:::
+
+### 文件后缀区分
+
+但例如第二种情况，Treeshaking 的方式并不能保证代码被完全分离。Modern.js 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
+
+例如在代码中引入了 `fs-extra`，这时候直接引用到组件中，会造成 CSR 加载报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
+
+```ts title="compat.ts"
+export { readFileSync } from 'fs-extra';
+```
+
+```ts title="compat.node.ts"
+export const readFileSync: any = () => {};
+```
+
+在文件中直接引入 `./compat`，此时 SSR 环境下会优先使用 `.node.ts` 后缀的文件，CSR 环境下会使用 `.ts` 后缀的文件。
+
+```ts title="App.tsx"
+import { readFileSync } from './compat'
+
+export const loader = () => {
+  const file = readFileSync('./myfile');
+  return {
+    ...
+  };
+};
+```
+
+### 独立文件
+
+上述两种方式，都会为开发者带来一些心智负担。Modern.js 基于[嵌套路由](/guides/basic-features/routes)开发设计了[更简单的方案](/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+
+## 接口请求
+
+在 SSR 中发起接口请求时，开发者有时自己封装了同构的请求工具。部分接口需要传递用户 Cookie，开发者可以通过 [`useRuntimeContext`](/guides/basic-features/data-fetch#route-loader) API 获取到请求头来实现。
+
+需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
+
+如果实在需要透传所有请求头，请务必过滤 `host` 字段。
+
+## 流式渲染
+
+Modern.js 支持了 React 18 的流式渲染，可以通过如下配置修改默认的渲染模式：
+
+```json
+{
+  "server": {
+    "ssr": {
+      "mode": "stream"
+    }
+  }
+}
+```
+
+:::note
+目前 Modern.js 内置的数据获取方式还未支持流式渲染，如迫切需要开发者可以按照 React Stream SSR 的 Demo 自建。
+
+:::

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

@@ -0,0 +1,48 @@
+---
+sidebar_position: 10
+---
+
+# 测试
+
+Modern.js 默认继承了 [Jest](https://jestjs.io/) 的测试能力。
+
+我们首先需要执行 `pnpm run new` 启用「单元测试 / 集成测试」功能：
+
+```
+? 请选择你想要的操作： 启用可选功能
+? 启用可选功能： 启用「单元测试 / 集成测试」功能
+```
+
+执行上述命令后，`package.json` 中将会自动生成 `"test": "modern test"` 命令。
+
+在 `modern.config.ts` 中注册 Test 插件：
+
+```ts title="modern.config.ts"
+import testPlugin from '@modern-js/plugin-testing';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  ...,
+  plugins: [..., testPlugin()],
+});
+```
+
+## 测试文件
+
+Modern.js 默认识别的测试文件路径为：`<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
+
+如果你需要自定义 test 目录，可通过 [tools.jest](/configure/app/tools/jest) 进行配置。
+
+## 使用姿势
+
+Modern.js test 支持使用 [testing-library](https://testing-library.com/docs/) 相关包 API，可直接通过 `@modern-js/runtime/testing` 进行导入:
+
+```
+import { render, screen } from '@modern-js/runtime/testing';
+```
+
+其他 Modern.js 支持的 testing API 可参考[这里](/apis/app/runtime/testing/cleanup)。
+
+## transform
+
+Modern.js 测试默认使用 [babel-jest](https://www.npmjs.com/package/babel-jest) 进行源码编译，如果你需要使用 [ts-jest](https://github.com/kulshekhar/ts-jest)，可以通过 [testing.transform](/configure/app/testing/transformer) 进行配置。