静态站点生成（SSG）

功能介绍

在生产环境的构建中，Rspress 会自动帮你生成静态站点，即生成各个页面的 HTML 内容，在构建完成之后，HTML 会出现在默认的产物目录中，比如：

  1. doc_build
  2. ├── static # 静态资源
  3. │   ├── main.js
  4. │   └── ...
  5. ├── index.html # 首页
  6. ├── about.html # 关于页
  7. ├── posts
  8. │   ├── hello-world.html # 文章页
  9. │   └── ...

你可以将这个产物目录的内容部署到任何静态站点托管服务上，比如 GitHub Pages、Netlify、Vercel 等。

SSG 的优势

静态站点生成的本质是在构建阶段进行组件的预渲染，将组件渲染成 HTML 字符串，然后写入到 HTML 文件中，这样做有诸多的好处，比如：

  • 首屏渲染速度更快，因为不需要等待 JS 加载完成之后再进行渲染。
  • 更利于 SEO，因为搜索引擎爬虫可以直接抓取到完整的 HTML 内容。

而考虑到静态站点生成的成本，Rspress 只有在生产环境构建时才会进行预渲染，而在开发环境下，仍然是采用传统的 SPA 渲染模式，没有进行预渲染。

添加自定义站点内容

通过 builderConfig.html.tags，你可以自定义站点 HTML 内容，比如添加统计代码、添加脚本和样式等。

rspress.config.ts

  1. import { defineConfig } from 'rspress/config';
  3. export default defineConfig({
  4.   // ...
  5.   builderConfig: {
  6.     html: {
  7.       tags: [
  8.         {
  9.           tag: 'script',
  10.           attrs: {
  11.             src: 'https://cdn.example.com/your-script.js',
  12.           },
  13.         },
  14.         {
  15.           tag: 'link',
  16.           attrs: {
  17.             rel: 'stylesheet',
  18.             href: 'https://cdn.example.com/your-style.css',
  19.           },
  20.         },
  21.       ],
  22.     },
  23.   },
  24. });

关于 builderConfig.html.tags 更详细的配置，请参考文档。

预览产物

在生产环境构建完成之后，你可以通过 rspress preview 命令来预览产物，这个命令会启动一个本地的静态站点服务，你可以在浏览器中访问这个服务来预览产物。

  1. > rspress preview
  3. Preview server running at http://localhost:4173/

关闭 SSG

如果你不想使用静态站点生成，可以通过 ssg 配置来关闭它。

rspress.config.ts

  1. import { defineConfig } from 'rspress/config';
  3. export default defineConfig({
  4.   // ...
  5.   ssg: false,
  6. });

注意

请谨慎关闭 SSG，因为这会丧失上文中提到的静态站点生成的诸多优势。