如何通过GitHub Actions将Node.js Web应用部署至GitHub Pages？

前提确认 #

你的Node.js应用需要能生成静态文件产物（比如React/Vue/Next.js静态导出等），GitHub Pages仅支持静态内容托管。

步骤1：配置项目构建命令 #

确保package.json中包含正确的构建命令，示例：

{
  "scripts": {
    "build": "react-scripts build" // React项目示例，Vue对应"vite build"，Next.js静态导出对应"next build"
  }
}

构建完成后，静态文件会生成在build（React）、dist（Vue/Vite）或out（Next.js静态导出）目录，记好这个目录路径。

步骤2：创建GitHub Actions工作流文件 #

在项目根目录新建路径.github/workflows/deploy.yml，粘贴以下内容（根据你的项目调整构建产物目录）：

name: Deploy to GitHub Pages

# 触发条件：推送代码到main分支时执行
on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write # 赋予Actions推送内容的权限
    steps:
      # 拉取仓库代码
      - name: Checkout code
        uses: actions/checkout@v4

      # 设置Node.js环境
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20 # 替换为你的项目所需Node.js版本
          cache: 'npm' # 缓存npm依赖，加速构建

      # 安装依赖
      - name: Install dependencies
        run: npm ci # 用ci命令更适合CI环境，依赖package-lock.json

      # 构建静态文件
      - name: Build static files
        run: npm run build

      # 部署到GitHub Pages
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build # 替换为你的构建产物目录，比如./dist或./out

步骤3：配置GitHub Pages设置 #

1. 打开你的GitHub仓库，进入Settings -> Pages
2. 在「Source」区域，选择「GitHub Actions」作为部署源（Actions运行成功后，这里会自动识别到部署记录）

步骤4：触发部署 #

推送代码到main分支，GitHub会自动触发Actions工作流。你可以在仓库的Actions标签页查看构建和部署进度。

常见问题处理 #

• 单页应用（SPA）路由问题：GitHub Pages默认不会处理SPA的前端路由，刷新非根页面会返回404。解决方法：
  • 在构建产物目录中复制index.html并重命名为404.html，这样GitHub Pages会把404请求重定向到这个文件，SPA框架就能处理路由了
  • 或者使用Hash模式路由（比如React Router的HashRouter）
• 自定义域名：在仓库Settings -> Pages中配置自定义域名，同时在构建产物目录添加CNAME文件（内容为你的自定义域名）
• 依赖安装失败：确保你的package-lock.json或yarn.lock已提交到仓库，使用npm ci或yarn install --frozen-lockfile保证依赖版本一致

内容的提问来源于stack exchange，提问作者John Burton