跳到正文
@amamo/doctrine
本页目录

部署到 GitHub Pages

GitHub Pages 项目网站通常位于 https://owner.github.io/repository/。只要构建收到最终公开 URL， Doctrine 就能处理这段子路径。

1. 在本地验证生产构建

添加 CI 前，先使用相同的公开地址结构：

Shell
doctrine build docs --site-url https://owner.github.io/repository/

如果要检查导航与搜索，请通过静态服务器打开生成的 dist/index.html。不要使用 file: URL； module script 和 Pagefind 都需要 HTTP 服务。

2. 启用 Actions 部署

打开仓库的 Settings → Pages，把 Source 设置为 GitHub Actions。

3. 添加工作流

创建 .github/workflows/deploy-docs.yml：

YAML
name: Deploy documentation

on:
  push:
    branches: [main]
  workflow_dispatch:

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

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

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - id: pages
        uses: actions/configure-pages@v6
      - run: doctrine build docs --site-url "${{ steps.pages.outputs.base_url }}"
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v5

这些版本与本仓库验证过的 Pages 工具链一致。请按使用方项目修改分支、包管理器、内容目录或 输出目录，并让上传 path 与 --out-dir 或 outDir 保持一致。

为什么 base_url 很重要

actions/configure-pages 返回配置后的 Pages URL：项目网站会包含 /repository/，自定义域名也会 反映在这里。Doctrine 归一化该 URL，再把 pathname 用于：

  • CSS 与 JavaScript 资源
  • 默认 MDX 链接与导航
  • 语言路由与切换
  • Pagefind 请求和结果链接
  • canonical 与 alternate 元数据
  • 404.html 引用的脚本和样式

Artifact 仍包含 dist/index.html，而不是 dist/repository/index.html。GitHub Pages 在服务 artifact 时添加仓库前缀。

自定义域名与其他静态托管

Pages 配置自定义域名后，同一工作流仍然适用，因为 base_url 会反映该设置。使用其他静态托管 时，传入其最终 HTTP(S) URL 执行同一个构建，再上传输出目录内容即可。生产环境不需要 Node.js 进程。

常见问题

  • 工作流无法部署： 确认 Pages 使用 GitHub Actions，并且 job 拥有 pages: write 和 id-token: write。
  • 资源、导航或搜索返回 404： 确认 --site-url 包含完整仓库 pathname，并结束于公开网站 root。
  • Artifact 上传找不到文件： 让 path 与 --out-dir 或配置的 outDir 一致。
  • 构建拒绝 outDir： 它必须位于项目 root 内、内容目录外，并且不能就是 root。
  • 原生绑定无法加载： 在 @amamo/mdx 支持的平台安装依赖，不要从其他机器复制 node_modules。
copyright © 2026 白熱。