GitHub Pages 部署

GitHub Pages 免费托管静态站点，是 Slidev 演示文稿最常见的部署方式。配合 GitHub Actions，每次推代码自动构建发布，零服务器成本。

部署方式概览

两种主流方式：

方式	适用场景
GitHub Actions 自动部署	推送即发布，推荐
手动上传产物	一次部署，快速

GitHub Actions 工作流

在仓库创建 .github/workflows/deploy.yml，推送代码后自动构建并发布：

name: Deploy Slidev

on:
  push:
    branches: [main]

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build -- --base /repo/
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

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

要点：

• 触发条件：推送到 main 分支
• 权限：写入 Pages 需要 pages: write 与 id-token: write
• 构建：npm ci 安装依赖，npm run build 产出 dist
• 子路径部署记得加 --base /仓库名/
• 上传 dist 后由 deploy-pages 动作发布

Pages 设置

仓库开启 Pages：

1. 进入仓库 Settings → Pages
2. Source 选择 GitHub Actions
3. 保存后，Actions 工作流部署完成即可访问

访问地址规则：

仓库类型	地址
用户/组织主页	https://用户名.github.io
项目仓库	https://用户名.github.io/仓库名/

项目仓库的地址带子路径，构建时必须配置 --base /仓库名/。

package.json 脚本

为 Actions 提供构建入口：

{
  "scripts": {
    "build": "slidev build --base /repo/",
    "dev": "slidev",
    "export": "slidev export"
  }
}

• npm run build 对应 Actions 中的构建步骤
• 本地与 CI 共用一套命令，行为一致
• 子路径随仓库名固定写死，避免忘记参数

手动部署备选

不走 Actions 时，本地构建后手动推送：

# 1. 本地构建
slidev build --base /repo/

# 2. 推送到 gh-pages 分支
npx gh-pages -d dist

或直接把 dist 内容推送到仓库分支，交给 Pages 从分支发布。

常见问题

问题	处理
样式丢失/资源 404	检查 --base 是否与仓库路径一致
Actions 无权限	确认 permissions 段已声明 pages: write
部署不触发	确认工作流文件名与分支名匹配
首次部署地址 404	等待几分钟，或检查仓库名大小写

使用建议

• 默认走 Actions：推送即发布，免去手动操作
• 固定 base：子路径部署把 --base 写进 build 脚本，避免遗漏
• 版本管理：不同分支可对应不同演示版本，灵活切换
• 自定义域名：Pages 设置中绑定自有域名（CNAME 记录）

GitHub Actions + Pages 让 Slidev 演示文稿实现「推代码 → 自动构建 → 自动发布」的全自动化链路。