#项目部署

这一节我们将来讲解项目的部署环节，我们假定你已经完成了项目的开发，现在需要将项目部署到线上。你需要考虑如下的方面：

• 项目生产环境构建和预览；
• 静态资源前缀配置；
• 项目基础路径配置；
• 选择部署平台进行部署。

#项目生产环境构建和预览

在部署之前，我们需要先对项目进行生产环境的构建，并在本地进行预览，以确保项目能够正常运行。在 Rspress 项目中，我们可以通过下面的 scripts 命令来进行构建和预览：

{
  "scripts": {
    "build": "rspress build",
    "preview": "rspress preview"
  }
}

值得关注的是，最后的产物会被输出到项目根目录的 doc_build 目录下，这个目录下的内容就是我们需要部署的内容。

#静态资源前缀配置

我们可以把部署产物分为两部分：HTML 文件和静态资源。HTML 文件指的是产物目录中的 HTML 文件，这些文件是我们最终部署到服务器上的文件。

而所谓的静态资源，指的是产物目录中的 static 目录，里面包含了项目所需的 JavaScript、CSS、图片等静态资源。在部署时，如果你想将这些静态资源放到 CDN 上以保证更好的访问性能，而不是像 HTML 一样直接放到服务器上，那么你需要配置静态资源的前缀，这样才能让项目正确地引用到这些静态资源，可以通过 builderConfig.output.assetPrefix 来完成：

import { defineConfig } from '@rspress/core';

export default defineConfig({
  builderConfig: {
    output: {
      assetPrefix: 'https://cdn.com/',
    },
  },
});

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

<script src="https://cdn.com/static/js/app.123.js"></script>

#项目基础路径配置

在部署的时候，我们可能需要将项目部署到一个子路径下，比如，如果你计划将你的站点部署到 https://foo.github.io/bar/，那么你应该将 base 参数设置为 "/bar/"：

import { defineConfig } from '@rspress/core';

export default defineConfig({
  base: '/bar/',
});

更多说明可参考 base 配置文档。

#选择部署平台进行部署

在完成了上面的配置之后，我们就可以将构建产物部署到服务器上了。你有很多种选择，比如 Zephyr、GitHub Pages、Netlify、Vercel 等等。这里我们以 Zephyr、GitHub Pages 和 Netlify 为例，来讲解如何部署。

#通过 Zephyr Cloud 部署

Zephyr Cloud 是一个零配置的部署平台，它可以直接集成到你的构建流程中，并提供全球边缘分发能力。

#如何部署

请按照 zephyr-rspress-plugin 中的步骤进行操作。

在构建过程中，你的 Rspress 文档站点将会被自动部署，并生成一个可访问的部署 URL。

Zephyr Cloud 会处理资源优化、全球 CDN 分发，并为你的文档站点提供自动回滚功能。

#通过 GitHub Actions 部署

如果你的项目是托管在 GitHub 上的，那么你可以通过 GitHub Pages 来进行部署。GitHub Pages 是 GitHub 提供的一个静态网站托管服务，它可以让你直接将你的项目部署到 GitHub 上，而不需要你自己搭建服务器。

#1. 创建 Workflow 文件

首先，你需要在项目根目录下创建一个名为 .github/workflows/deploy.yml 的文件，内容如下：

name: Deploy Rspress site to Pages

on:
  push:
    branches: [main]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      - uses: pnpm/action-setup@v3 # pnpm is optional but recommended, you can also use npm / yarn
        with:
          version: 8
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Install dependencies
        run: pnpm install
      - name: Build with Rspress
        run: |
          pnpm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: doc_build

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

#2. 配置 GitHub Actions

在仓库 Settings 界面中的 Pages 栏目中，你可以选择 GitHub Actions 作为部署源。

#3. 推送代码到 main 分支

当你将代码推送到 main 分支的时候，GitHub Actions 就会自动执行部署流程，你可以在 Actions 栏目中查看部署的进度。当部署完成之后，你就可以通过 https://<username>.github.io/<repository>/ 来访问你的站点了。

#通过 Netlify 部署

Netlify 是一个 Web 应用部署平台，它可以让你直接将你的项目部署到 Netlify 上，而不需要你自己搭建服务器。

#完成基础配置

在 Netlify 上部署项目非常简单，你只需要引入你的 GitHub 仓库，然后配置一些基础信息就可以部署了，主要配置下面两个字段即可：

• Build command：构建命令，这里我们填写项目中的 build 命令即可，如 npm run build。
• Publish directory：产物目录，这里我们填写项目中的产物目录 doc_build。

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

#配置自定义域名

如果你想要将你的站点绑定到自己的域名上，那么你可以在 Netlify 的 Domain management 栏目中进行配置，具体的配置方法可以参考 Netlify 官方文档。

#通过 Kinsta 部署

你可以在 Kinsta 上部署你的 Rspress 网站。

1. 登录或创建账户，来查看你的 MyKinsta 面板。

2. 通过 Git 提供商授权 Kinsta。

3. 从左侧边栏选择 Static Sites，然后点击 Add sites。

4. 选择需要部署的仓库和分支。

5. 在构建设置中，Kinsta 会尝试自动填写 Build command、Node version 以及 Publish directory。如果没有自动填写，请填写以下内容：

   • 构建命令: npm run build
   • Node 版本: 18.16.0
   • 发布目录: doc_build

6. 点击 Create site。

#常见问题

#刷新页面时出现 404

如果你的站点在导航时正常，但刷新页面后出现 404 错误，请参考 SSG 文档中的「刷新页面时出现 404」 章节。