@modern-js/main-doc 3.11.3 → 3.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/en/community/contributing-guide.mdx +5 -3
- package/docs/en/configure/app/html/meta.mdx +18 -8
- package/docs/en/configure/app/output/ssg.mdx +11 -2
- package/docs/en/configure/app/server/static-cache-control.mdx +55 -0
- package/docs/en/guides/basic-features/deploy.mdx +6 -0
- package/docs/en/guides/basic-features/html.mdx +1 -10
- package/docs/en/guides/basic-features/render/ssg.mdx +57 -2
- package/docs/zh/community/contributing-guide.mdx +5 -3
- package/docs/zh/configure/app/html/meta.mdx +18 -8
- package/docs/zh/configure/app/output/ssg.mdx +11 -2
- package/docs/zh/configure/app/server/static-cache-control.mdx +55 -0
- package/docs/zh/guides/basic-features/deploy.mdx +6 -0
- package/docs/zh/guides/basic-features/html.mdx +1 -10
- package/docs/zh/guides/basic-features/render/ssg.mdx +57 -2
- package/package.json +2 -2
|
@@ -92,11 +92,13 @@ pnpm run reset
|
|
|
92
92
|
|
|
93
93
|
## Testing
|
|
94
94
|
|
|
95
|
-
###
|
|
95
|
+
### Validate Changes and Retain Regression Tests
|
|
96
96
|
|
|
97
|
-
|
|
97
|
+
Do not add new test files or fixtures by default. When fixing bugs or adding features, reuse existing tests or provide evidence through temporary scripts or manual black-box validation. Record commands, results and checks not run in the PR. Temporary validation does not need to be committed as permanent tests.
|
|
98
98
|
|
|
99
|
-
|
|
99
|
+
Retain permanent regression tests only to protect specific user-visible behavior or public contracts that existing coverage does not protect, and explain why they are needed. Do not duplicate existing integration flows with layer-by-layer mocked unit tests. Prefer lightweight black-box input/output tests for pure logic rather than internal invocation-order assertions. Do not narrow TypeScript types to replace validation. Snapshots may cover stable user output or public protocols, but should not lock down implementation details.
|
|
100
|
+
|
|
101
|
+
Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository, with existing cases in `<PACKAGE_DIR>/tests`. Run `pnpm check-test-governance` to check your changes. The existing 52 directories under `tests/integration` are frozen. New allowlist entries require human maintainer approval and the `approved-new-integration-fixture` PR label. See the repository's [test governance guide](https://github.com/web-infra-dev/modern.js/blob/main/scripts/test-governance/README.md) for all rules, commands and inline exceptions.
|
|
100
102
|
|
|
101
103
|
### Run Unit Tests
|
|
102
104
|
|
|
@@ -10,19 +10,29 @@ title: meta
|
|
|
10
10
|
```js
|
|
11
11
|
const defaultMeta = {
|
|
12
12
|
charset: { charset: 'utf-8' },
|
|
13
|
-
viewport:
|
|
14
|
-
'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
|
|
15
|
-
'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
|
|
16
|
-
renderer: 'webkit',
|
|
17
|
-
layoutmode: 'standard',
|
|
18
|
-
imagemode: 'force',
|
|
19
|
-
'wap-font-scale': 'no',
|
|
20
|
-
'format-detection': 'telephone=no',
|
|
13
|
+
viewport: 'width=device-width, initial-scale=1',
|
|
21
14
|
};
|
|
22
15
|
```
|
|
23
16
|
|
|
24
17
|
Configure the `<meta>` tag of the HTML.
|
|
25
18
|
|
|
19
|
+
The default viewport allows users to zoom the page. If your app needs to fill the screen or disable automatic telephone number detection, configure those behaviors explicitly:
|
|
20
|
+
|
|
21
|
+
```ts title="modern.config.ts"
|
|
22
|
+
import { defineConfig } from '@modern-js/app-tools';
|
|
23
|
+
|
|
24
|
+
export default defineConfig({
|
|
25
|
+
html: {
|
|
26
|
+
meta: {
|
|
27
|
+
viewport: 'width=device-width, initial-scale=1, viewport-fit=cover',
|
|
28
|
+
'format-detection': 'telephone=no',
|
|
29
|
+
},
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Setting `viewport` replaces the entire default string, so include `width=device-width` and `initial-scale=1` when customizing it. When using `viewport-fit=cover`, account for the device's safe areas in your page styles.
|
|
35
|
+
|
|
26
36
|
import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
|
|
27
37
|
|
|
28
38
|
<RsbuildConfig configName="html.meta" />
|
|
@@ -23,13 +23,13 @@ The SSG feature is closely related to routing. It is recommended to understand t
|
|
|
23
23
|
|
|
24
24
|
- Use `output.ssg` for single-entry apps.
|
|
25
25
|
- For multi-entry apps, prefer `output.ssgByEntries`.
|
|
26
|
-
- If `output.ssg` is `true` and `output.ssgByEntries` is not set,
|
|
26
|
+
- If `output.ssg` is `true` and `output.ssgByEntries` is not set, SSG is enabled for all entries, using the route collection rules below.
|
|
27
27
|
|
|
28
28
|
:::
|
|
29
29
|
|
|
30
30
|
## Boolean Type
|
|
31
31
|
|
|
32
|
-
When this configuration is set to `true`, the SSG feature will be enabled for all entries by default. For **manual routing**, the root route of the entry will be rendered. For **conventional routing**,
|
|
32
|
+
When this configuration is set to `true`, the SSG feature will be enabled for all entries by default. For **manual routing**, the root route of the entry will be rendered. For **conventional routing**, non-dynamic routes and paths returned by page-level `ssgParams` generators will be rendered. Dynamic routes without a generator are skipped.
|
|
33
33
|
|
|
34
34
|
```js
|
|
35
35
|
export default defineConfig({
|
|
@@ -50,6 +50,7 @@ type SSGRouteOptions =
|
|
|
50
50
|
| string
|
|
51
51
|
| {
|
|
52
52
|
url: string;
|
|
53
|
+
output?: string;
|
|
53
54
|
headers?: Record<string, any>;
|
|
54
55
|
};
|
|
55
56
|
|
|
@@ -59,6 +60,14 @@ type SSGOptions = {
|
|
|
59
60
|
};
|
|
60
61
|
```
|
|
61
62
|
|
|
63
|
+
### Route Collection
|
|
64
|
+
|
|
65
|
+
- With `routes` omitted or set to `[]`, conventional routing automatically includes non-dynamic routes and paths generated by `ssgParams` in file-system `page.data.ts` or `$.data.ts` files. Generator discovery does not apply to config routes.
|
|
66
|
+
- With a non-empty `routes` list, render the listed paths and paths from `ssgParams`. Other non-dynamic routes are skipped. When an explicit route and `ssgParams` resolve to the same URL, render it once using the explicit route's options, including `headers` and `output`.
|
|
67
|
+
- Setting the entry's SSG option to `false` also disables its parameter generators.
|
|
68
|
+
|
|
69
|
+
These rules also apply to each entry configured through `output.ssgByEntries`. See [generating parameters alongside a loader](/guides/basic-features/render/ssg#generating-parameters-alongside-a-loader) for parameter types, encoding, and examples.
|
|
70
|
+
|
|
62
71
|
### Example
|
|
63
72
|
|
|
64
73
|
In the example configuration below, SSG will render the pages corresponding to the `/`, `/about`, and `/user/:id` routes.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: staticCacheControl
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# server.staticCacheControl
|
|
6
|
+
|
|
7
|
+
- **Type:** `boolean | object`
|
|
8
|
+
- **Default:** `true`
|
|
9
|
+
|
|
10
|
+
Set the `Cache-Control` header of static files served by the production server.
|
|
11
|
+
|
|
12
|
+
By default:
|
|
13
|
+
|
|
14
|
+
| File | `Cache-Control` |
|
|
15
|
+
| -------------------------------------------------------------------------------------------------------- | ------------------------------------- |
|
|
16
|
+
| Build assets with a content hash in the file name, such as `static/js/main.3f2a1b9c0d.js` | `public, max-age=31536000, immutable` |
|
|
17
|
+
| Other static files, such as files in `config/public` and `config/upload`, or build assets without a hash | `no-cache` |
|
|
18
|
+
|
|
19
|
+
A file is treated as hashed only when it is in a build output directory (`static/` or a custom [`output.distPath`](/configure/app/output/dist-path) for JS, CSS and media) and its name contains a content hash. Files from `config/public`, `config/upload` and `server.publicDir` are never treated as hashed. With `no-cache`, browsers keep the file but check with the server before using it, which costs a request but no download when the file hasn't changed.
|
|
20
|
+
|
|
21
|
+
Every static file also gets an `ETag`, computed from the content that is sent, and a request with a matching `If-None-Match` header is answered with `304 Not Modified` without a body. The content comes from the server's file cache, so a `304` doesn't read the file from disk again.
|
|
22
|
+
|
|
23
|
+
The values above apply in production. During development every static file gets `no-cache`, so edited files are never served from the browser cache. The header is not added to HTML pages. Use a [custom middleware](/guides/advanced-features/web-server) if you need it there.
|
|
24
|
+
|
|
25
|
+
A `Cache-Control` or `ETag` header set by a route's response headers, or a `Cache-Control` set by a custom middleware before or after `await next()`, takes precedence.
|
|
26
|
+
|
|
27
|
+
### Custom values
|
|
28
|
+
|
|
29
|
+
```ts title="modern.config.ts"
|
|
30
|
+
export default defineConfig({
|
|
31
|
+
server: {
|
|
32
|
+
staticCacheControl: {
|
|
33
|
+
hashed: 'public, max-age=86400',
|
|
34
|
+
unhashed: 'public, max-age=300',
|
|
35
|
+
},
|
|
36
|
+
},
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| Name | Type | Default | Description |
|
|
41
|
+
| ---------- | -------- | ------------------------------------- | -------------------------------------- |
|
|
42
|
+
| `hashed` | `string` | `public, max-age=31536000, immutable` | `Cache-Control` of hashed build assets |
|
|
43
|
+
| `unhashed` | `string` | `no-cache` | `Cache-Control` of other static files |
|
|
44
|
+
|
|
45
|
+
### Disable
|
|
46
|
+
|
|
47
|
+
```ts title="modern.config.ts"
|
|
48
|
+
export default defineConfig({
|
|
49
|
+
server: {
|
|
50
|
+
staticCacheControl: false,
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Static files then only get an `ETag`, and conditional requests with `If-None-Match` are still answered with `304`.
|
|
@@ -116,6 +116,12 @@ Setting `DEBUG` to a non-empty value also enables `verbose` logging, unless `MOD
|
|
|
116
116
|
|
|
117
117
|
This environment variable controls the built-in server logger. It does not override a custom logger or enable logging when `server.logger` is `false`.
|
|
118
118
|
|
|
119
|
+
### Static asset caching
|
|
120
|
+
|
|
121
|
+
The built-in Node.js production server sets `Cache-Control: public, max-age=31536000, immutable` for build assets with a content hash in the file name, and `no-cache` for other static files. Every static file also gets an `ETag`, so unchanged files are revalidated with a `304` response. HTML pages are not changed.
|
|
122
|
+
|
|
123
|
+
To change or disable these headers, see [`server.staticCacheControl`](/configure/app/server/static-cache-control).
|
|
124
|
+
|
|
119
125
|
## Netlify
|
|
120
126
|
|
|
121
127
|
Netlify is a popular Web development platform designed for building, deploying, and maintaining modern web projects. Deploying on Netlify mainly requires configuring the `netlify.toml` file.
|
|
@@ -110,16 +110,7 @@ The above JSX components will generate the following HTML template:
|
|
|
110
110
|
<html>
|
|
111
111
|
<head>
|
|
112
112
|
<meta charset="utf-8" />
|
|
113
|
-
<meta
|
|
114
|
-
name="viewport"
|
|
115
|
-
content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
|
|
116
|
-
/>
|
|
117
|
-
<meta http-equiv="x-ua-compatible" content="ie=edge" />
|
|
118
|
-
<meta name="renderer" content="webkit" />
|
|
119
|
-
<meta name="layoutmode" content="standard" />
|
|
120
|
-
<meta name="imagemode" content="force" />
|
|
121
|
-
<meta name="wap-font-scale" content="no" />
|
|
122
|
-
<meta name="format-detection" content="telephone=no" />
|
|
113
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
123
114
|
<link rel="icon" href="/a.icon" />
|
|
124
115
|
<script defer src="/static/js/builder-runtime.js"></script>
|
|
125
116
|
<script defer src="/static/js/lib-react.js"></script>
|
|
@@ -102,7 +102,7 @@ The above example introduces single-entry scenarios. For more information, refer
|
|
|
102
102
|
|
|
103
103
|
## Adding Dynamic Routes
|
|
104
104
|
|
|
105
|
-
|
|
105
|
+
For manual routing, provide concrete paths directly in `routes`. You can also use this configuration for conventional routing with dynamic segments (for example, `/user/[id]`).
|
|
106
106
|
|
|
107
107
|
```js
|
|
108
108
|
export default defineConfig({
|
|
@@ -114,6 +114,61 @@ export default defineConfig({
|
|
|
114
114
|
});
|
|
115
115
|
```
|
|
116
116
|
|
|
117
|
+
### Generating Parameters Alongside a Loader
|
|
118
|
+
|
|
119
|
+
For file-system conventional routing, export `ssgParams` from the page's `page.data.ts` to generate paths from route parameters. Enable SSG to use this convention. Generator discovery does not apply to config routes.
|
|
120
|
+
|
|
121
|
+
Use an explicit named export or re-export, such as `export { ssgParams } from './params'`. Exports available only through `export *` are not discovered.
|
|
122
|
+
|
|
123
|
+
For example, `src/routes/blog/[slug]/page.data.ts` can share the published-post selection logic with its loader:
|
|
124
|
+
|
|
125
|
+
{/* prettier-ignore */}
|
|
126
|
+
```ts title="src/routes/blog/[slug]/page.data.ts"
|
|
127
|
+
import type { SSGParams } from '@modern-js/plugin-ssg'
|
|
128
|
+
import { getPublishedPosts } from '@/data/posts'
|
|
129
|
+
|
|
130
|
+
export const ssgParams: SSGParams = async () => {
|
|
131
|
+
const posts = await getPublishedPosts()
|
|
132
|
+
return posts.map(post => ({ slug: post.slug }))
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export const loader = async ({ params }: { params: { slug: string } }) => {
|
|
136
|
+
const posts = await getPublishedPosts()
|
|
137
|
+
const post = posts.find(post => post.slug === params.slug)
|
|
138
|
+
if (!post) {
|
|
139
|
+
throw new Response('Not Found', { status: 404 })
|
|
140
|
+
}
|
|
141
|
+
return post
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
If the published posts have the slugs `hello` and `getting-started`, Modern.js generates `/blog/hello` and `/blog/getting-started`. With `routes` omitted or empty, it also prerenders the entry's non-dynamic routes. The loader still reads data for one page and runs during prerendering. Its return value is not used to enumerate paths.
|
|
146
|
+
|
|
147
|
+
`ssgParams` takes no arguments and returns an array of parameter objects, synchronously or asynchronously. It runs once per page route during the SSG build, in Node.js using the application's server compilation. It can use path aliases and server dependencies such as filesystem access. SSG uses the existing server data-loader boundary to keep the generator and its server dependencies out of browser bundles. When debugging code that imports Node.js dependencies, [enable SSR during development](#development-debugging). The function is not called by `dev` or `serve`.
|
|
148
|
+
|
|
149
|
+
#### Parameter Values
|
|
150
|
+
|
|
151
|
+
Each path segment can contain ASCII letters, digits, `-`, `.`, `_`, or `~`. Empty segments, `.`, and `..` are rejected. A slug such as `release.v3` generates an `index.html` inside that page's directory.
|
|
152
|
+
|
|
153
|
+
| Route file | Parameter object | Generated path |
|
|
154
|
+
| ---------------------------------------- | ----------------------------------- | ------------------------------ |
|
|
155
|
+
| `routes/[lang]/blog/[slug]/page.data.ts` | `{ lang: 'en', slug: 'hello' }` | `/en/blog/hello` |
|
|
156
|
+
| `routes/blog/[slug$]/page.data.ts` | `{}` | `/blog` |
|
|
157
|
+
| `routes/blog/[slug$]/page.data.ts` | `{ slug: 'hello' }` | `/blog/hello` |
|
|
158
|
+
| `routes/docs/$.data.ts` | `{ '*': 'guides/getting-started' }` | `/docs/guides/getting-started` |
|
|
159
|
+
|
|
160
|
+
For nested routes, each object must include all required parent and child parameters. Parameters are not collected or combined from `layout.data.ts`. Omit an optional parameter or set it to `undefined` to omit that segment. For a wildcard page (`$.tsx`), export `ssgParams` from `$.data.ts` and use the `'*'` key. Use `/` between segments of a wildcard value.
|
|
161
|
+
|
|
162
|
+
An empty array adds no paths for that page. You can still list a path for it explicitly in `routes`. Duplicate generated paths are rendered once. Dynamic routes without `ssgParams` remain excluded from automatic SSG.
|
|
163
|
+
|
|
164
|
+
A missing required parameter, a non-string value other than `undefined` for an optional parameter, an invalid result, or an exception fails the build with a route-specific error.
|
|
165
|
+
|
|
166
|
+
#### Combining Explicit and Generated Paths
|
|
167
|
+
|
|
168
|
+
A non-empty `output.ssg.routes` list is combined with the paths returned by `ssgParams`. For example, with `routes: ['/about']` and the blog generator above, Modern.js prerenders `/about`, `/blog/hello`, and `/blog/getting-started`. Other non-dynamic paths are included only if explicitly listed or returned by a generator.
|
|
169
|
+
|
|
170
|
+
When both sources produce the same URL, Modern.js renders it once with the explicit route's options, including its `headers` and `output`. Omitting `routes` or setting `routes: []` also includes non-dynamic routes automatically. The same rules apply to `output.ssgByEntries`. Disabling SSG for an entry also disables its generators.
|
|
171
|
+
|
|
117
172
|
## SSG Matching for Parent and Child Routes
|
|
118
173
|
|
|
119
174
|
For a blog, `src/routes/blog/page.tsx` renders the list and `src/routes/blog/[slug]/page.tsx` renders an article. After enabling SSG, you can prerender both the list and selected articles:
|
|
@@ -139,7 +194,7 @@ Each path generates its own static HTML. The built-in production server matches
|
|
|
139
194
|
|
|
140
195
|
Requests to a trailing-slash URL such as `/blog/` receive an HTTP 308 redirect to `/blog`, preserving the query string. For example, `/blog/?preview=1` redirects to `/blog?preview=1`.
|
|
141
196
|
|
|
142
|
-
The SSG page at `/blog` does not act as a fallback for `/blog/*`. Defining a `[slug]` route does not automatically generate static HTML for every slug. List
|
|
197
|
+
The SSG page at `/blog` does not act as a fallback for `/blog/*`. Defining a `[slug]` route does not automatically generate static HTML for every slug. List concrete paths in `routes`, generate them with `ssgParams`, or combine both.
|
|
143
198
|
|
|
144
199
|
This example does not enable SSR or prerender the root entry `/`. An unmatched path therefore receives the root entry's CSR shell, and routing continues in the browser. The initial HTML response is typically HTTP 200. An unknown slug alone does not cause the server to return 404.
|
|
145
200
|
|
|
@@ -91,11 +91,13 @@ pnpm run reset
|
|
|
91
91
|
|
|
92
92
|
## 测试
|
|
93
93
|
|
|
94
|
-
###
|
|
94
|
+
### 验证变更与保留回归测试
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
默认不新增测试文件或 fixtures。修复 bug 或添加功能时,优先复用现有测试,或通过临时脚本、手动黑盒验证提供证据,并在 PR 中记录命令、结果及未执行的检查。临时验证不需要作为永久测试提交。
|
|
97
97
|
|
|
98
|
-
|
|
98
|
+
仅在需要保护明确的用户行为或公共契约、且现有覆盖不足时保留永久回归测试,并说明其必要性。不要为已有集成流程增加逐层 mock 的重复单测。纯逻辑优先使用轻量黑盒测试,断言输入输出而非内部调用顺序。不要通过收紧 TypeScript 类型来替代验证。快照可用于稳定的用户输出或公共协议,不用于锁定内部实现细节。
|
|
99
|
+
|
|
100
|
+
Modern.js 仓库的单元测试统一使用 [Rstest](https://rstest.rs/),已有用例位于 `<PACKAGE_DIR>/tests`。运行 `pnpm check-test-governance` 检查本次改动。`tests/integration` 已冻结现有 52 个目录,新增清单条目需要维护者人工批准及 PR 标签 `approved-new-integration-fixture`。完整规则、命令和行内例外格式见仓库的 [测试治理说明](https://github.com/web-infra-dev/modern.js/blob/main/scripts/test-governance/README.md)。
|
|
99
101
|
|
|
100
102
|
### 运行单元测试
|
|
101
103
|
|
|
@@ -10,19 +10,29 @@ title: meta
|
|
|
10
10
|
```js
|
|
11
11
|
const defaultMeta = {
|
|
12
12
|
charset: { charset: 'utf-8' },
|
|
13
|
-
viewport:
|
|
14
|
-
'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
|
|
15
|
-
'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
|
|
16
|
-
renderer: 'webkit',
|
|
17
|
-
layoutmode: 'standard',
|
|
18
|
-
imagemode: 'force',
|
|
19
|
-
'wap-font-scale': 'no',
|
|
20
|
-
'format-detection': 'telephone=no',
|
|
13
|
+
viewport: 'width=device-width, initial-scale=1',
|
|
21
14
|
};
|
|
22
15
|
```
|
|
23
16
|
|
|
24
17
|
配置 HTML 页面的 `<meta>` 标签。
|
|
25
18
|
|
|
19
|
+
默认 viewport 允许用户缩放页面。如果应用需要铺满屏幕或关闭电话号码自动识别,可以按需配置:
|
|
20
|
+
|
|
21
|
+
```ts title="modern.config.ts"
|
|
22
|
+
import { defineConfig } from '@modern-js/app-tools';
|
|
23
|
+
|
|
24
|
+
export default defineConfig({
|
|
25
|
+
html: {
|
|
26
|
+
meta: {
|
|
27
|
+
viewport: 'width=device-width, initial-scale=1, viewport-fit=cover',
|
|
28
|
+
'format-detection': 'telephone=no',
|
|
29
|
+
},
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
设置 `viewport` 会替换整个默认字符串,因此自定义时需保留 `width=device-width` 和 `initial-scale=1`。使用 `viewport-fit=cover` 时,还需在页面样式中处理设备安全区。
|
|
35
|
+
|
|
26
36
|
import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
|
|
27
37
|
|
|
28
38
|
<RsbuildConfig configName="html.meta" />
|
|
@@ -23,13 +23,13 @@ SSG 功能使用与路由关联性较大,建议使用前先了解[路由方案
|
|
|
23
23
|
|
|
24
24
|
- 单入口建议使用 `output.ssg`。
|
|
25
25
|
- 多入口建议优先使用 `output.ssgByEntries`。
|
|
26
|
-
- 当 `output.ssg` 为 `true` 且未配置 `output.ssgByEntries`
|
|
26
|
+
- 当 `output.ssg` 为 `true` 且未配置 `output.ssgByEntries` 时,所有入口都会启用 SSG,并遵循下文的路由收集规则。
|
|
27
27
|
|
|
28
28
|
:::
|
|
29
29
|
|
|
30
30
|
## Boolean 类型
|
|
31
31
|
|
|
32
|
-
当该配置设置为 `true` 时,将会默认开启所有入口的 SSG
|
|
32
|
+
当该配置设置为 `true` 时,将会默认开启所有入口的 SSG 功能。对**自控式路由**而言,将会渲染入口的根路由。对**约定式路由**而言,将会渲染非动态路由和页面级 `ssgParams` 生成的路径,未提供参数生成函数的动态路由会被跳过。
|
|
33
33
|
|
|
34
34
|
```js
|
|
35
35
|
export default defineConfig({
|
|
@@ -50,6 +50,7 @@ type SSGRouteOptions =
|
|
|
50
50
|
| string
|
|
51
51
|
| {
|
|
52
52
|
url: string;
|
|
53
|
+
output?: string;
|
|
53
54
|
headers?: Record<string, any>;
|
|
54
55
|
};
|
|
55
56
|
|
|
@@ -59,6 +60,14 @@ type SSGOptions = {
|
|
|
59
60
|
};
|
|
60
61
|
```
|
|
61
62
|
|
|
63
|
+
### 路由收集
|
|
64
|
+
|
|
65
|
+
- 不设置 `routes` 或设置为 `[]` 时,约定式路由会自动包含非动态路由,以及文件系统路由的 `page.data.ts` 或 `$.data.ts` 中 `ssgParams` 生成的路径。配置式路由不参与参数生成函数的发现。
|
|
66
|
+
- `routes` 非空时,渲染显式列出的路径和 `ssgParams` 生成的路径,跳过其他非动态路由。两者得到同一个 URL 时只渲染一次,使用显式路由的 `headers`、`output` 等配置。
|
|
67
|
+
- 将入口的 SSG 配置设为 `false`,也会禁用其参数生成函数。
|
|
68
|
+
|
|
69
|
+
这些规则同样适用于通过 `output.ssgByEntries` 配置的各个入口。参数类型、编码规则和示例请参考[在 Loader 旁生成路由参数](/guides/basic-features/render/ssg#在-loader-旁生成路由参数)。
|
|
70
|
+
|
|
62
71
|
### 示例
|
|
63
72
|
|
|
64
73
|
下面的示例配置中,SSG 会渲染 `/`、`/about` 和 `/user/:id` 三条路由对应的页面。
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: staticCacheControl
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# server.staticCacheControl
|
|
6
|
+
|
|
7
|
+
- **类型:** `boolean | object`
|
|
8
|
+
- **默认值:** `true`
|
|
9
|
+
|
|
10
|
+
设置生产服务器返回的静态文件的 `Cache-Control` 响应头。
|
|
11
|
+
|
|
12
|
+
默认值如下:
|
|
13
|
+
|
|
14
|
+
| 文件 | `Cache-Control` |
|
|
15
|
+
| ------------------------------------------------------------------------------------ | ------------------------------------- |
|
|
16
|
+
| 文件名包含内容哈希的构建产物,例如 `static/js/main.3f2a1b9c0d.js` | `public, max-age=31536000, immutable` |
|
|
17
|
+
| 其他静态文件,例如 `config/public` 和 `config/upload` 中的文件,或不带哈希的构建产物 | `no-cache` |
|
|
18
|
+
|
|
19
|
+
只有位于构建产物目录(`static/` 或自定义的 JS、CSS、媒体资源 [`output.distPath`](/configure/app/output/dist-path))中,并且文件名包含内容哈希的文件,才会被视为带哈希的构建产物。来自 `config/public`、`config/upload` 和 `server.publicDir` 的文件始终不会被视为带哈希的构建产物。使用 `no-cache` 时,浏览器会缓存文件,但每次使用前都会向服务器确认。文件未变化时只需一次请求,不需要重新下载。
|
|
20
|
+
|
|
21
|
+
所有静态文件都会带上根据实际返回内容计算的 `ETag`。如果请求中的 `If-None-Match` 与之匹配,服务器会直接返回不带响应体的 `304 Not Modified`。文件内容来自服务器的文件缓存,返回 `304` 时不会再次从磁盘读取文件。
|
|
22
|
+
|
|
23
|
+
以上取值在生产环境中生效。开发环境中所有静态文件都使用 `no-cache`,修改后的文件不会从浏览器缓存中读取。HTML 页面不会添加该响应头,如有需要,可以通过[自定义中间件](/guides/advanced-features/web-server)设置。
|
|
24
|
+
|
|
25
|
+
路由响应头中设置的 `Cache-Control` 或 `ETag`,以及在自定义中间件中 `await next()` 之前或之后设置的 `Cache-Control`,会优先生效。
|
|
26
|
+
|
|
27
|
+
### 自定义取值
|
|
28
|
+
|
|
29
|
+
```ts title="modern.config.ts"
|
|
30
|
+
export default defineConfig({
|
|
31
|
+
server: {
|
|
32
|
+
staticCacheControl: {
|
|
33
|
+
hashed: 'public, max-age=86400',
|
|
34
|
+
unhashed: 'public, max-age=300',
|
|
35
|
+
},
|
|
36
|
+
},
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| 名称 | 类型 | 默认值 | 说明 |
|
|
41
|
+
| ---------- | -------- | ------------------------------------- | ---------------------------------- |
|
|
42
|
+
| `hashed` | `string` | `public, max-age=31536000, immutable` | 带哈希的构建产物的 `Cache-Control` |
|
|
43
|
+
| `unhashed` | `string` | `no-cache` | 其他静态文件的 `Cache-Control` |
|
|
44
|
+
|
|
45
|
+
### 关闭
|
|
46
|
+
|
|
47
|
+
```ts title="modern.config.ts"
|
|
48
|
+
export default defineConfig({
|
|
49
|
+
server: {
|
|
50
|
+
staticCacheControl: false,
|
|
51
|
+
},
|
|
52
|
+
});
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
关闭后静态文件只会带上 `ETag`,带有 `If-None-Match` 的条件请求仍然会返回 `304`。
|
|
@@ -115,6 +115,12 @@ MODERN_SERVER_LOG_LEVEL=verbose node .output/index
|
|
|
115
115
|
|
|
116
116
|
该环境变量仅控制内置的服务器 logger,不会覆盖自定义 logger,也不会在 `server.logger` 为 `false` 时启用日志。
|
|
117
117
|
|
|
118
|
+
### 静态资源缓存
|
|
119
|
+
|
|
120
|
+
内置 Node.js 生产服务器会为文件名包含内容哈希的构建产物设置 `Cache-Control: public, max-age=31536000, immutable`,为其他静态文件设置 `no-cache`。所有静态文件还会带上 `ETag`,未变化的文件会通过 `304` 响应重新验证。HTML 页面不受影响。
|
|
121
|
+
|
|
122
|
+
如需修改或关闭这些响应头,请参阅 [`server.staticCacheControl`](/configure/app/server/static-cache-control)。
|
|
123
|
+
|
|
118
124
|
## Netlify
|
|
119
125
|
|
|
120
126
|
Netlify 是一个流行的 Web 开发平台,专为构建、发布和维护现代 Web 项目而设计。在 Netlify 上部署,通常需要配置 `netlify.toml` 文件,你可以根据项目复杂度,渐进地配置该文件。
|
|
@@ -113,16 +113,7 @@ export default function Document(): React.ReactElement {
|
|
|
113
113
|
<html>
|
|
114
114
|
<head>
|
|
115
115
|
<meta charset="utf-8" />
|
|
116
|
-
<meta
|
|
117
|
-
name="viewport"
|
|
118
|
-
content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
|
|
119
|
-
/>
|
|
120
|
-
<meta http-equiv="x-ua-compatible" content="ie=edge" />
|
|
121
|
-
<meta name="renderer" content="webkit" />
|
|
122
|
-
<meta name="layoutmode" content="standard" />
|
|
123
|
-
<meta name="imagemode" content="force" />
|
|
124
|
-
<meta name="wap-font-scale" content="no" />
|
|
125
|
-
<meta name="format-detection" content="telephone=no" />
|
|
116
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
126
117
|
<link rel="icon" href="/a.icon" />
|
|
127
118
|
<script defer src="/static/js/builder-runtime.js"></script>
|
|
128
119
|
<script defer src="/static/js/lib-react.js"></script>
|
|
@@ -103,7 +103,7 @@ export default defineConfig({
|
|
|
103
103
|
|
|
104
104
|
## 添加动态路由
|
|
105
105
|
|
|
106
|
-
|
|
106
|
+
在自控式路由中,直接在 `routes` 中写入具体路径。包含动态段的约定式路由(如 `/user/[id]`)也可以使用这一配置。
|
|
107
107
|
|
|
108
108
|
```js
|
|
109
109
|
export default defineConfig({
|
|
@@ -115,6 +115,61 @@ export default defineConfig({
|
|
|
115
115
|
});
|
|
116
116
|
```
|
|
117
117
|
|
|
118
|
+
### 在 Loader 旁生成路由参数
|
|
119
|
+
|
|
120
|
+
基于文件系统的约定式路由支持在页面的 `page.data.ts` 中导出 `ssgParams`,根据路由参数生成路径。启用 SSG 即可使用这一约定。配置式路由不参与参数生成函数的发现。
|
|
121
|
+
|
|
122
|
+
请使用显式命名导出或重导出,例如 `export { ssgParams } from './params'`。仅通过 `export *` 导出的函数不会被发现。
|
|
123
|
+
|
|
124
|
+
例如,`src/routes/blog/[slug]/page.data.ts` 可以与 loader 共享筛选已发布文章的逻辑:
|
|
125
|
+
|
|
126
|
+
{/* prettier-ignore */}
|
|
127
|
+
```ts title="src/routes/blog/[slug]/page.data.ts"
|
|
128
|
+
import type { SSGParams } from '@modern-js/plugin-ssg'
|
|
129
|
+
import { getPublishedPosts } from '@/data/posts'
|
|
130
|
+
|
|
131
|
+
export const ssgParams: SSGParams = async () => {
|
|
132
|
+
const posts = await getPublishedPosts()
|
|
133
|
+
return posts.map(post => ({ slug: post.slug }))
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
export const loader = async ({ params }: { params: { slug: string } }) => {
|
|
137
|
+
const posts = await getPublishedPosts()
|
|
138
|
+
const post = posts.find(post => post.slug === params.slug)
|
|
139
|
+
if (!post) {
|
|
140
|
+
throw new Response('Not Found', { status: 404 })
|
|
141
|
+
}
|
|
142
|
+
return post
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
如果已发布文章的 slug 是 `hello` 和 `getting-started`,Modern.js 会生成 `/blog/hello` 和 `/blog/getting-started`。如果 `routes` 未设置或为空,也会预渲染该入口中的非动态路由。loader 仍负责读取单个页面的数据,在预渲染时执行,其返回值不会用于枚举路径。
|
|
147
|
+
|
|
148
|
+
`ssgParams` 不接收参数,可以同步或异步返回参数对象数组。SSG 构建时,每个页面路由的函数执行一次,使用应用的服务端编译结果在 Node.js 中运行,因此可以使用路径别名和文件系统访问等服务端依赖。SSG 沿用服务端 data loader 的隔离机制,使参数生成函数及其服务端依赖不进入浏览器产物。调试包含 Node.js 依赖的代码时,请[在开发阶段启用 SSR](#开发环境调试)。`dev` 和 `serve` 不会调用该函数。
|
|
149
|
+
|
|
150
|
+
#### 参数值
|
|
151
|
+
|
|
152
|
+
路径段可包含 ASCII 字母、数字、`-`、`.`、`_` 或 `~`。空路径段、`.` 和 `..` 会被拒绝。包含点号的 slug(如 `release.v3`)会在对应页面目录中生成 `index.html`。
|
|
153
|
+
|
|
154
|
+
| 路由文件 | 参数对象 | 生成路径 |
|
|
155
|
+
| ---------------------------------------- | ----------------------------------- | ------------------------------ |
|
|
156
|
+
| `routes/[lang]/blog/[slug]/page.data.ts` | `{ lang: 'en', slug: 'hello' }` | `/en/blog/hello` |
|
|
157
|
+
| `routes/blog/[slug$]/page.data.ts` | `{}` | `/blog` |
|
|
158
|
+
| `routes/blog/[slug$]/page.data.ts` | `{ slug: 'hello' }` | `/blog/hello` |
|
|
159
|
+
| `routes/docs/$.data.ts` | `{ '*': 'guides/getting-started' }` | `/docs/guides/getting-started` |
|
|
160
|
+
|
|
161
|
+
嵌套路由的每个对象必须包含父子路由所需的全部必填参数,不会从 `layout.data.ts` 收集或组合参数。可选参数可以省略或设为 `undefined`,对应的路径段也会省略。对于通配页面(`$.tsx`),在 `$.data.ts` 中导出 `ssgParams`,通过 `'*'` 键传入路径,用 `/` 分隔路径段。
|
|
162
|
+
|
|
163
|
+
返回空数组时,该页面不会自动生成路径,仍可在 `routes` 中手动指定具体路径。生成的重复路径只渲染一次。没有导出 `ssgParams` 的动态路由仍不会参与自动 SSG。
|
|
164
|
+
|
|
165
|
+
缺少必填参数、参数值不是字符串(可选参数的 `undefined` 除外)、返回结果无效或函数抛出异常时,构建会失败并报告对应路由。
|
|
166
|
+
|
|
167
|
+
#### 组合显式路径和生成路径
|
|
168
|
+
|
|
169
|
+
非空的 `output.ssg.routes` 会与 `ssgParams` 返回参数生成的路径合并。例如,设置 `routes: ['/about']` 并使用上面的博客参数函数时,Modern.js 会预渲染 `/about`、`/blog/hello` 和 `/blog/getting-started`。其他非动态路由只有被显式列出或由参数函数生成时才会加入。
|
|
170
|
+
|
|
171
|
+
如果两边得到同一个 URL,只渲染一次,并使用显式路由的 `headers`、`output` 等配置。`routes` 未设置或为 `[]` 时,也会自动收集非动态路由。`output.ssgByEntries` 遵循同样的规则。关闭入口的 SSG 也会禁用其参数生成函数。
|
|
172
|
+
|
|
118
173
|
## 父子路由的 SSG 匹配
|
|
119
174
|
|
|
120
175
|
以博客为例,`src/routes/blog/page.tsx` 是列表页,`src/routes/blog/[slug]/page.tsx` 是文章页。启用 SSG 后,可以同时预渲染列表页和指定的文章页:
|
|
@@ -140,7 +195,7 @@ export default defineConfig({
|
|
|
140
195
|
|
|
141
196
|
访问 `/blog/` 这样的尾部斜杠形式时,服务器会通过 HTTP 308 重定向到 `/blog`,并保留查询参数。例如,`/blog/?preview=1` 会重定向到 `/blog?preview=1`。
|
|
142
197
|
|
|
143
|
-
`/blog` 的 SSG 页面不会作为 `/blog/*` 的回退页面。即使应用定义了 `[slug]` 动态路由,也不会自动为所有 slug 生成静态 HTML
|
|
198
|
+
`/blog` 的 SSG 页面不会作为 `/blog/*` 的回退页面。即使应用定义了 `[slug]` 动态路由,也不会自动为所有 slug 生成静态 HTML,可以在 `routes` 中列出具体路径,通过 `ssgParams` 生成,或组合使用两者。
|
|
144
199
|
|
|
145
200
|
上例没有启用 SSR,也没有预渲染根入口 `/`,因此未命中的路径会返回根入口的 CSR 页面壳,由浏览器中的路由继续处理。此时初始 HTML 响应通常为 HTTP 200,不会因为路径中包含未知 slug 就在服务端返回 404。
|
|
146
201
|
|
package/package.json
CHANGED
|
@@ -16,14 +16,14 @@
|
|
|
16
16
|
"modern",
|
|
17
17
|
"modern.js"
|
|
18
18
|
],
|
|
19
|
-
"version": "3.
|
|
19
|
+
"version": "3.12.0",
|
|
20
20
|
"publishConfig": {
|
|
21
21
|
"registry": "https://registry.npmjs.org/",
|
|
22
22
|
"access": "public"
|
|
23
23
|
},
|
|
24
24
|
"dependencies": {
|
|
25
25
|
"mermaid": "^11.17.2",
|
|
26
|
-
"@modern-js/sandpack-react": "3.
|
|
26
|
+
"@modern-js/sandpack-react": "3.12.0"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
29
|
"@rsbuild/plugin-sass": "2.0.1",
|