GitHub Pages 部署静态网站流程、常见问题以及解决方案

GitHub Pages 介绍

相信有很多小伙伴会问，在没有云服务器的时候，个人作品、技术文档、博客等内容能让大家都能访问吗？答案肯定是不行的🙅，为什么呢，因为个人开发的作品只能在本地启动后查看，或者在同一局域网下，通过 NetWork 访问，那么如果想要大家在任何网络任何地方任何时间想要访问的话能实现吗？很明确的告诉大家伙，可以，那么就让我带着大家一步一步的把杰作放到一个大家都可以访问的地方

GitHub Pages 和 Gitee Pages 曾是国内开发者常用的两大平台。然而，Gitee 自 2022 年 1 月 1 日起，对非企业用户停止免费提供 Gitee Pages 服务，这使得众多开发者将目光更多地投向了 GitHub Pages

GitHub Pages 作为 GitHub 提供的一项免费静态网站托管服务，有着强大的生态集成优势，但也存在一些不便之处：

不稳定。GitHub 服务器位于国外，GitHub 访问和代码提交都有可能会因为网络问题操作失败

不过，凭借其丰富的开源资源、与 GitHub 仓库的无缝衔接等特点，它依然是当下部署静态网站的热门选择。接下来，我们就深入探讨一下如何使用 GitHub Pages 部署静态网站，以及在这个过程中可能遇到的常见问题和解决方案

想要快速的了解 GitHub Pages 的整个流程的伙伴，可直接跳到（五）

GitHub Pages 部署静态网站流程

（一）准备工作

确保本地已安装 Node.js 和 Git，并且能够正常连接 GitHub。
拥有一个已经开发完成且在本地测试正常的静态网站项目，例如使用 Vue3 编写的应用，或者是基于 VitePress 搭建的文档网站。
将项目代码推送到 GitHub 仓库。

（二）配置项目（以 Vue3 和 VitePress 项目为例）

Vue3 项目：

如果使用 Vue CLI 搭建项目，打开 vue.config.js 文件，若网站不是部署在根路径（http://ip:端口/vue），添加 publicPath 配置，示例如下：

javascript 复制代码

module.exports = {
  publicPath: '/vue/' // 替换为你的 GitHub 仓库名称，注意以 / 开头和结尾
};

如果是 Vite 搭建的 Vue3 项目，打开 vite.config.js 文件，添加 base 配置：

javascript 复制代码

export default {
  base: '/vue/' // 替换为你的 GitHub 仓库名称，注意以 / 开头和结尾
};

VitePress 项目 ：打开 .vitepress/config.js 或 .vitepress/config.ts 文件，添加或修改 base 配置，使其与 GitHub 仓库名称一致（以 / 开头和结尾），示例如下：

javascript 复制代码

export const config: UserConfig = {
  base: '/vue/',
  // 其他配置如 title、description、themeConfig 等...
};

（三）创建 GitHub Actions 工作流文件（自动化部署）

在项目根目录下创建 .github/workflows 目录（如果不存在），然后在该目录下创建 deploy.yml 文件。

Vue3 项目配置示例：

javascript 复制代码

# 工作流名称：部署 VitePress 站点到 GitHub Pages
name: Deploy Vue3 Site to GitHub Pages

# 触发条件：当 master 分支有代码推送时，自动执行此工作流
on:
  push:
    branches: [master]  # 根据实际情况修改为你的主分支名称，如 master 等

jobs:
  deploy:
    # 运行环境：使用 GitHub 提供的 Ubuntu 最新版虚拟服务器
    runs-on: ubuntu-latest
    steps:
      # 步骤 1：拉取仓库代码
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0    # 拉取所有历史提交（确保能获取完整代码）

      # 步骤 2：配置 Node.js 环境（版本 20，且缓存 npm 依赖加速安装）
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20  # 可根据项目需求选择合适的 Node.js 版本
          cache: npm

      # 步骤 3：安装依赖
      - name: Install dependencies
        run: npm install  # 安装项目依赖

      # 步骤 4：构建静态网站（执行 npm 脚本，生成可部署的静态文件）
      - name: Build
        run: npm run build  # 运行构建命令，根据项目实际情况可能是 yarn build

      # 步骤 5：部署到 GitHub Pages（核心步骤，将构建产物推送到 gh-pages 分支）
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4    # 使用成熟的部署 Action
        with:
          # 身份验证：使用仓库 Secrets 中配置的令牌（需有仓库写权限）
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir:./dist  # 构建产物目录，根据实际情况调整
          keep_files: false    # 部署前清空 gh-pages 分支旧文件
          force_orphan: true    # 强制创建独立的 gh-pages 分支（覆盖旧分支）

VitePress 项目配置示例：

javascript 复制代码

name: Deploy VitePress Site to GitHub Pages

on:
  push:
    branches: [master]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20  # 可根据项目需求选择合适的 Node.js 版本
          cache: npm

      # 清理缓存并重新安装依赖（解决依赖缺失或版本不一致问题）
      - name: Clean npm cache and reinstall dependencies
        run: |
          npm cache clean --force
          rm -rf node_modules package-lock.json
          npm install --force

      - name: Build
        run: npm run docs:build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir:./.vitepress/dist  # VitePress 构建产物目录
          keep_files: false
          force_orphan: true

（四）提交代码并触发部署

将修改后的配置文件（包括 deploy.yml 以及可能修改的项目配置文件）和项目代码提交到 GitHub 仓库的主分支。

（五）配置 GitHub Pages

打开 GitHub 仓库页面，点击顶部的 Settings，在左侧菜单找到 Pages（位于 Code and automation 分类下）。在 Source 部分：

选择部署来源为 Deploy from a branch。
选择分支为 gh-pages（GitHub Actions 会自动创建该分支并推送构建产物）。
选择目录为 / (root)。
点击 Save 保存设置。

很多小伙伴肯定不太理解 GitHub Pages 的工作原理，下面我配合图文详细和大家伙分析一下，相信大伙看完后会对这个自动化流程有初步的理解。

GitHub Pages 中的配置中的"Deploy from a branch""gh-pages""/(root)" 是它的部署规则：

"Deploy from a branch"：以监听分支的形式部署

"gh-pages"：具体监听哪个分支

"/(root)"：将分支根目录的文件部署为可访问的网站

整个过程总结：

deploy.yml 是 "自动化桥梁"：将代码构建 和分支推送 两个步骤自动化，确保每次代码更新都能生成最新静态文件并推送到 gh-pages

GitHub Pages 是 "展示层"：监听 gh-pages 分支的变化，将分支中的静态文件渲染为可访问的网站

实现了 "代码提交 → 自动构建 → 自动部署 → 网站更新" 的全流程自动化

（六）查看构建结果

打开 GitHub 仓库页面，点击顶部的 Actions，可以看到构建成功还是失败，点击具体某一条可以查看具体详情，如果构建成功，点击链接即可看到网站；构建失败的话可以看到哪里出问题了。

（七）访问网站

配置完成后，等待一段时间（通常几分钟内），即可通过 https://[用户名].github.io/[仓库名]/ 访问部署好的静态网站。

常见问题及解决方案

（一）构建成功了，访问链接只看到了一个仓库名字

问题描述：在构建没有任何问题的情况下，打开链接看到的不是自己的在本地开发的时候看到的页面，而是一个只带有一个 github 仓库名字的类似于404一样的界面。

原因分析：deploy.yml 这个文件中有一个很关键的字段 publish_dir ，这个字段的意思呢就是把构建出来的产物也就是 dist 文件夹推送到 gh-pages 分支，这个过程是通过 deploy.yml 这个文件实现的。如果 publish_dir 写的内容不是项目构建之后 dist 文件夹所在的位置的话就会出现这个问题。

解决方案：检查 deploy.yml 中的 publish_dir 字段，看看你构建之后产物的位置是否和 publish_dir 字段写的一致，可以在本地开发的时候执行 npm run docs:build 看构建之后的 dist 在什么位置，然后 publish_dir 就写构建物所在的路径。

（二）权限相关问题

问题描述 ：在使用 GitHub Actions 部署时，出现类似 remote: {"auth_status":"access_denied_to_user","body":"Permission to [仓库名].git denied to github-actions[bot]."} 的错误，导致 Git 推送失败。

原因分析 ：GitHub Actions 默认使用的 GITHUB_TOKEN 权限不足，无法向仓库推送分支。

解决方案：

生成具有 repo 权限的个人访问令牌（PAT）：登录 GitHub，进入 Settings -> Developer settings -> Personal access tokens -> Tokens (classic)，点击 Generate new token (classic)，配置好令牌名称、有效期，并勾选 repo 权限后生成令牌。
将令牌添加到仓库 Secrets：在仓库的 Settings -> Secrets and variables -> Actions 中，点击 New repository secret，Name 填写自定义名称（如 ACTIONS_DEPLOY_TOKEN），Secret 粘贴生成的令牌。
修改 GitHub Actions 配置：在 .github/workflows/deploy.yml 中，将 github_token 替换为 ${``{ secrets.ACTIONS_DEPLOY_TOKEN }}。

（三）依赖安装问题

问题描述 ：执行 npm ci 或 npm install 时，出现找不到模块的错误，比如 Error: Cannot find module @rollup/rollup-linux-x64-gnu。

原因分析：可能是由于依赖安装不完整、缓存问题或者 npm 版本问题导致某些可选依赖没有正确安装。

解决方案：

本地清理并重新安装依赖：在项目根目录执行 rm -rf node_modules package-lock.json，然后 npm install，安装完成后可以本地测试构建 npm run docs:build（VitePress 项目）或 npm run build（Vue3 项目），确保本地构建正常。
修改 GitHub Actions 配置：在 .github/workflows/deploy.yml 中，在安装依赖步骤添加 --force 参数强制重新安装，并清理 npm 缓存，示例如下：

javascript 复制代码

- name: Clean npm cache and reinstall dependencies
  run: |
    npm cache clean --force
    rm -rf node_modules package-lock.json
    npm install --force

（四）构建路径与静态资源加载问题

问题描述：部署后的网站只有标题，页面内容不全，静态资源（如 CSS、JavaScript、图片）无法正常加载。

原因分析 ：项目配置中的基础路径（如 Vue3 项目的 publicPath、VitePress 项目的 base）设置错误，导致静态资源的路径不正确。

解决方案 ：确保基础路径与 GitHub 仓库名称完全一致，且格式为 /仓库名/。例如：

Vue3 + Vue CLI 项目：

javascript 复制代码

module.exports = {
  publicPath: '/your-repo-name/'
};

Vue3 + Vite 项目：

javascript 复制代码

export default {
  base: '/your-repo-name/'
};

VitePress 项目：

javascript 复制代码

export const config: UserConfig = {
  base: '/your-repo-name/'
};

（五）Action 配置参数错误问题

问题描述 ：使用 GitHub Actions 时，出现类似 Warning: Unexpected input(s) 'cleanup', valid inputs are ['deploy_key', 'github_token'...] 的警告，且部署失败。

原因分析 ：在 peaceiris/actions-gh-pages@v4 等 Action 配置中，使用了不支持的参数。解决方案 ：参考对应 Action 的官方文档，确认支持的参数并修改配置。比如要实现清理旧文件的效果，cleanup 参数不可用，可以使用 keep_files: false 替代，同时可以添加 force_orphan: true 来强制推送覆盖旧内容，示例配置如下：

javascript 复制代码

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
    publish_dir: ./dist  # 构建产物目录，根据实际情况调整
    keep_files: false
    force_orphan: true

结语

GitHub Pages 作为当下主流的静态网站部署平台，尽管存在服务器在国外导致的代码提交和网站访问不稳定等问题，但在 Gitee Pages 对非企业用户停止免费服务后，仍是开发者部署静态网站的重要选择。通过本文对部署流程的详细介绍，以及对常见问题和解决方案的梳理，相信能帮助开发者更顺利地将 Vue3 应用、VitePress 文档等静态网站部署到 GitHub Pages 上。在部署过程中，只要重点关注基础路径配置、依赖管理、权限设置以及 GitHub Actions 的正确使用，就能让静态网站稳定、高效地运行，充分发挥 GitHub Pages 与开源生态无缝衔接的优势，展示出自己的技术成果。