静态站点生成(SSG)
SSG(Static Site Generation)是一种基于数据与模板,在构建时渲染完整静态网页的技术解决方案。这意味着在生产环境中,页面默认就是有内容的,并且可以被 CDN 缓存。对于无需数据的页面,SSG 可以提供更好的性能和更高的安全性。
启用 SSG
要在 Modern.js 项目中启用 SSG 功能,请按照以下步骤修改代码:
- 安装 SSG 插件依赖
如果项目尚未安装 SSG 插件,请先安装:
请确保 @modern-js/plugin-ssg 的版本与项目中 @modern-js/app-tools 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布,版本不一致可能导致兼容性问题。
请先查看 @modern-js/app-tools 的版本,然后安装相同版本的 @modern-js/plugin-ssg:
- 配置 modern.config.ts
在 modern.config.ts 文件中导入并添加 SSG 插件,同时配置 output.ssg:
- 单入口请使用
output.ssg。 - 多入口请使用
output.ssgByEntries。 - 当仅设置
output.ssg: true且未配置output.ssgByEntries时,所有入口下的所有路由都会作为 SSG 路由处理。
开发环境调试
SSG 也是在 Node.js 环境渲染页面,因此我们可以在开发阶段开启 SSR,提前暴露代码问题,验证 SSG 渲染效果:
在约定式路由中使用
约定式路由中,Modern.js 根据入口下的文件结构生成路由,因此框架能够收集完整的路由信息。
基本用法
例如,以下是一个使用约定式路由的项目目录结构:
上述文件目录将会生成以下三条路由:
//user/user/profile
如果还不了解约定式路由的规则,可以先查看路由方案。
在 src/routes/page.tsx 中添加组件代码:
在项目根路径下执行 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 时,默认只会渲染入口路由即 /:
如果我们希望同时开启 /about 的 SSG 功能,可以配置 output.ssg:
执行 pnpm run build 后,可以看到 dist/ 目录中,新增了一个 main/about/index.html 文件。
执行 pnpm run serve 启动项目后,访问页面,在浏览器我们工具的 Network 窗口,查看请求返回的文档,文档包含组件渲染后的完整页面内容。
以上仅介绍了单入口的情况,更多相关内容可以查看 API 文档。
添加动态路由
在自控式路由中,直接在 routes 中写入具体路径。包含动态段的约定式路由(如 /user/[id])也可以使用这一配置。
在 Loader 旁生成路由参数
基于文件系统的约定式路由支持在页面的 page.data.ts 中导出 ssgParams,根据路由参数生成路径。启用 SSG 即可使用这一约定。配置式路由不参与参数生成函数的发现。
请使用显式命名导出或重导出,例如 export { ssgParams } from './params'。仅通过 export * 导出的函数不会被发现。
例如,src/routes/blog/[slug]/page.data.ts 可以与 loader 共享筛选已发布文章的逻辑:
如果已发布文章的 slug 是 hello 和 getting-started,Modern.js 会生成 /blog/hello 和 /blog/getting-started。如果 routes 未设置或为空,也会预渲染该入口中的非动态路由。loader 仍负责读取单个页面的数据,在预渲染时执行,其返回值不会用于枚举路径。
ssgParams 不接收参数,可以同步或异步返回参数对象数组。SSG 构建时,每个页面路由的函数执行一次,使用应用的服务端编译结果在 Node.js 中运行,因此可以使用路径别名和文件系统访问等服务端依赖。SSG 沿用服务端 data loader 的隔离机制,使参数生成函数及其服务端依赖不进入浏览器产物。调试包含 Node.js 依赖的代码时,请在开发阶段启用 SSR。dev 和 serve 不会调用该函数。
参数值
路径段可包含 ASCII 字母、数字、-、.、_ 或 ~。空路径段、. 和 .. 会被拒绝。包含点号的 slug(如 release.v3)会在对应页面目录中生成 index.html。
嵌套路由的每个对象必须包含父子路由所需的全部必填参数,不会从 layout.data.ts 收集或组合参数。可选参数可以省略或设为 undefined,对应的路径段也会省略。对于通配页面($.tsx),在 $.data.ts 中导出 ssgParams,通过 '*' 键传入路径,用 / 分隔路径段。
返回空数组时,该页面不会自动生成路径,仍可在 routes 中手动指定具体路径。生成的重复路径只渲染一次。没有导出 ssgParams 的动态路由仍不会参与自动 SSG。
缺少必填参数、参数值不是字符串(可选参数的 undefined 除外)、返回结果无效或函数抛出异常时,构建会失败并报告对应路由。
组合显式路径和生成路径
非空的 output.ssg.routes 会与 ssgParams 返回参数生成的路径合并。例如,设置 routes: ['/about'] 并使用上面的博客参数函数时,Modern.js 会预渲染 /about、/blog/hello 和 /blog/getting-started。其他非动态路由只有被显式列出或由参数函数生成时才会加入。
如果两边得到同一个 URL,只渲染一次,并使用显式路由的 headers、output 等配置。routes 未设置或为 [] 时,也会自动收集非动态路由。output.ssgByEntries 遵循同样的规则。关闭入口的 SSG 也会禁用其参数生成函数。
父子路由的 SSG 匹配
以博客为例,src/routes/blog/page.tsx 是列表页,src/routes/blog/[slug]/page.tsx 是文章页。启用 SSG 后,可以同时预渲染列表页和指定的文章页:
两条路径分别生成自己的静态 HTML。使用内置生产服务器访问时,SSG 页面按路径精确匹配:
访问 /blog/ 这样的尾部斜杠形式时,服务器会通过 HTTP 308 重定向到 /blog,并保留查询参数。例如,/blog/?preview=1 会重定向到 /blog?preview=1。
/blog 的 SSG 页面不会作为 /blog/* 的回退页面。即使应用定义了 [slug] 动态路由,也不会自动为所有 slug 生成静态 HTML,可以在 routes 中列出具体路径,通过 ssgParams 生成,或组合使用两者。
上例没有启用 SSR,也没有预渲染根入口 /,因此未命中的路径会返回根入口的 CSR 页面壳,由浏览器中的路由继续处理。此时初始 HTML 响应通常为 HTTP 200,不会因为路径中包含未知 slug 就在服务端返回 404。
如果存在匹配的 SSR 入口,则由 SSR 渲染决定响应内容和状态码。没有可用入口时,服务器返回 404。如果将根入口 / 也配置为 SSG,它同样只匹配自身,不再提供通配回退。
处理预渲染时的 404
继续上例,如果将 /blog/scheduled 加入 output.ssg.routes,但文章尚未发布,loader 可以在构建时抛出 404。以下示例中,getPost 是业务侧的文章查询函数,publishedAt 是以毫秒为单位的发布时间戳:
预渲染收到 404 或其他非 2xx 响应时,会:
- 输出包含路径和状态码的构建警告。
- 跳过该页面的静态 HTML 文件和 SSG 路由注册。
- 继续生成其他正常响应的页面。
因此,错误页面不会被保存成之后以 HTTP 200 返回的静态页面。访问 /blog/scheduled 时,会按照上一节的入口回退规则处理,构建时的 404 不会被保存为该路径的运行时响应状态。
SSG 只在构建时生成页面,文章到达发布时间后不会自动补生成静态 HTML。需要重新构建并部署,才能生成该文章的 SSG 页面。
多入口
多入口应用请通过 output.ssgByEntries 按入口分别配置:
详细配置请参考:output.ssgByEntries
配置渲染请求头
Modern.js 支持为具体入口或路由配置请求头,例如:
上述配置中,为所有路由设置了 x-tt-env 请求头,单独为 /about 路由设置了 from 请求头。
路由中设置的 headers 会覆盖入口中设置的 headers。