部署静态站点

本章节介绍如何将 Rsbuild 的构建产物部署为静态站点。

背景信息

在开始进行部署前，你需要了解一些背景信息：

  • 用于构建和预览产物的 CLI 命令。
  • 构建产物的目录结构。
  • 静态资源的 URL 前缀。

构建命令

Rsbuild 提供的构建命令：

  • build 命令，用于生成部署到生产环境的构建产物；
  • preview 命令，用于在本地预览生产构建的产物, 注意你需要提前执行 rsbuild build 命令构建出对应产物。

package.json

  1. {
  2.   "scripts": {
  3.     "build": "rsbuild build",
  4.     "preview": "rsbuild preview"
  5.   }
  6. }

TIP

preview 命令仅用于本地预览，请勿将它用于生产服务器，因为它不是为此而设计的。

产物目录

Rsbuild 的构建产物通常包含 HTML、JS、CSS 等文件，默认输出到 dist 目录下，dist 目录的名称和结构可以通过一些配置项来修改，请参考 构建产物目录 章节来了解更多。

  1. dist
  2. ├── static
  3. │   ├── image
  4. │   ├── css
  5. │   └── js
  6. └── [name].html

静态资源前缀

我们可以把构建产物分为两部分：HTML 文件和静态资源。

  • HTML 文件指的是产物目录中 .html 后缀的文件，它们通常需要被部署到服务器上。
  • 静态资源位于产物目录中的 static 目录，里面包含了 JavaScript、CSS、图片等资源，它们可以被部署到服务器或者 CDN 上。

如果静态资源被部署到了服务器的某个子目录下，你可以将 output.assetPrefix 配置为一个 base 路径：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  3. export default defineConfig({
  4.   output: {
  5.     assetPrefix: '/some-base-folder/',
  6.   },
  7. });

你想要将静态资源放到 CDN 上，以保证更好的访问性能，而不是像 HTML 一样直接放到服务器上，那么你就需要将 output.assetPrefix 配置为 CDN 地址，使应用能够正确的引用到这些静态资源：

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  3. export default defineConfig({
  4.   output: {
  5.     assetPrefix: 'https://cdn.com/path/',
  6.   },
  7. });

这样，在 HTML 中引用静态资源的时候，就会自动加上指定的前缀，例如：

  1. <script src="https://cdn.com/path/static/js/index.some-hash.js"></script>

GitHub Pages

GitHub Pages 是一个静态站点托管服务，可以直接从 GitHub 上的存储库获取 HTML、CSS 和 JavaScript 文件。

下面是部署到 GitHub Pages 的步骤示例。

  1. 通过 output.assetPrefix 设置静态资源的 URL 前缀。

rsbuild.config.ts

  1. import { defineConfig } from '@rsbuild/core';
  3. export default defineConfig({
  4.   output: {
  5.     // 请将 <REPO_NAME> 替换为仓库的名称。
  6.     // 比如 "/my-project/"
  7.     assetPrefix: '/<REPO_NAME>/',
  8.   },
  9. });
  1. 打开 GitHub 仓库的 “Settings” 页面，点击左侧菜单的 “Pages” 选项，进入 GitHub Pages 的配置页面。
  2. 选择 “Source” -> “GitHub Actions”，点击 “create your own” 来创建 GitHub Action 配置文件。
  3. 将以下内容粘贴到输入框，将文件命名为 github-pages.yml（你可以根据需要来调整文件的内容和名称）。

github-pages.yml

  1. # 用于构建和部署 Rsbuild 站点到 GitHub Pages 的示例工作流
  2. name: Rsbuild Deployment
  4. on:
  5.   # 在推送到默认分支时触发
  6.   push:
  7.     branches: ['main']
  8.   # 允许你从 Actions Tabs 手动运行这个工作流
  9.   workflow_dispatch:
  11. # 设置 GITHUB_TOKEN 的权限以允许部署到 GitHub Pages
  12. permissions:
  13.   contents: read
  14.   pages: write
  15.   id-token: write
  17. # 同时只允许一个部署执行
  18. concurrency:
  19.   group: 'pages'
  20.   cancel-in-progress: false
  22. jobs:
  23.   build:
  24.     runs-on: ubuntu-latest
  26.     steps:
  27.       - name: Checkout
  28.         uses: actions/checkout@v4
  30.       - name: Use Node.js 20
  31.         uses: actions/setup-node@v3
  32.         with:
  33.           node-version: 20
  35.       # 如果你使用其他的包管理器，如 yarn 或 pnpm，
  36.       # 你需要先安装它们
  37.       - name: Install dependencies
  38.         run: npm i
  40.       - name: Build
  41.         run: npm run build
  43.       - name: Setup Pages
  44.         uses: actions/configure-pages@v5
  46.       - name: Upload artifact
  47.         uses: actions/upload-pages-artifact@v3
  48.         with:
  49.           path: './dist'
  51.       - name: Deploy to GitHub Pages
  52.         id: deployment
  53.         uses: actions/deploy-pages@v4
  1. 提交，等待 GitHub Actions 执行，执行完成后，你可以访问 https://<USERNAME>.github.io/<REPO_NAME>/ 来查看部署后的页面。

Netlify

Netlify Core 是一个针对开发者的前端云解决方案，使用现代、可组合的工具构建和部署具有未来兼容性的数字解决方案。

新增站点

Netlify 提供了详细的指南，你可以按照 Netlify - Add new site 操作，配置一些基础信息，就可以开始部署了。

你需要配置以下两个字段：

  • Build command：构建命令，填写项目的 build 命令即可，通常是 npm run build。
  • Publish directory：产物目录，填写项目中的产物目录，默认是 dist。

然后点击 Deploy site 按钮，就可以开始部署了。

配置域名

如果你想要使你的站点可以通过你自己的域名访问，那么你可以在 Netlify 的 “Domain management” 栏目中进行配置。

详细指南：Netlify - Custom domains。

Vercel

Vercel 是一个为开发者提供的平台，它提供了构建和快速部署网络应用所需的工具、工作流程和基础设施，无需额外的配置。

新增站点

Vercel 提供了详细的指南，你可以按照 Vercel - Projects 操作，在 dashboard 中创建一个项目，配置一些基础信息，就可以开始部署了。

你只需要配置 “Build and Output Settings” 下的字段：

  • Output directory：产物目录，填写项目中的产物目录，默认是 dist。

然后点击 Deploy 按钮，就可以开始部署了。

配置域名

如果你想要使你的站点可以通过你自己的域名访问，那么你可以在 Vercel 的 “Domains” 栏目中进行配置。

详细指南：Vercel - Domains。

Cloudflare Pages

Cloudflare Pages 是一个由 Cloudflare 提供的静态网站托管平台。

你可以按照 Cloudflare Pages - Git integration guide 操作，通过 Git 集成，将你的站点部署到 Cloudflare Pages。

在进行配置时，你需要填写 “Build settings” 中的以下字段：

  • Build command：构建命令，填写项目的 build 命令即可，通常是 npm run build。
  • Build output directory：产物目录，填写项目中的产物目录，默认是 dist。

然后点击 Save and Deploy 按钮，就可以开始部署了。