使用 GitHub Pages 部署前端静态网页完全指南

GitHub Pages 是 GitHub 提供的免费静态网页托管服务，专门用于托管前端静态页面（HTML/CSS/JS），无需服务器，操作简单，非常适合个人主页、项目演示、博客等场景。下面我会用新手友好的方式，一步步教你完成部署。

一、前置准备

在开始前，你需要准备这些基础环境/资源：

1. GitHub 账号：没有的话先去 GitHub 官网 注册

2. Git 环境：本地安装 Git（下载地址），并完成与 GitHub 的 SSH 或 HTTPS 认证（推荐 SSH，避免每次输密码）

3. 前端代码：准备好你的静态网页文件（核心是 index.html，必须有这个入口文件），确保代码是纯静态的（GitHub Pages 不支持 PHP/Node.js 等后端代码）

二、核心操作步骤

步骤 1：创建符合规则的 GitHub 仓库

GitHub Pages 对仓库命名有严格要求，决定了你的访问域名：

1. 登录 GitHub，点击右上角 + → New repository

2. 填写仓库信息：

   • 仓库名（关键）：

     • 方式 1（个人/组织主页）：必须是 <你的GitHub用户名>.github.io（比如我的用户名是 testuser，仓库名就是 testuser.github.io），这种方式部署后直接通过 https://<用户名>.github.io 访问

     • 方式 2（项目页面）：任意名称（比如 my-web），部署后访问地址是 https://<用户名>.github.io/<仓库名>/

   • 可见性：选 Public（GitHub Pages 仅支持公共仓库免费部署）

   • 勾选 Add a README file（可选，方便后续管理）

3. 点击 Create repository 创建仓库

步骤 2：上传前端代码到仓库

有两种方式上传代码，新手推荐先试「网页端上传」，熟悉后用「Git 命令行」更高效。

方式 A：网页端直接上传

1. 进入刚创建的仓库，点击页面上方的 Add file → Upload files

2. 拖拽你的所有前端文件（index.html、css/、js/、images/ 等）到上传区域，或点击 choose your files 选择文件

3. 拉到页面底部，填写提交信息（比如 Initial commit: upload web files），点击 Commit changes

方式 B：Git 命令行上传（推荐）

1. 打开本地终端/命令提示符，进入你的前端代码文件夹：

   
   cd /你的代码文件夹路径  # 比如 cd Desktop/my-web
   

2. 初始化 Git 仓库（如果还没初始化）：

   
   git init
   

3. 关联 GitHub 仓库（替换下面的仓库地址，可从 GitHub 仓库页面复制）：

   
   git remote add origin git@github.com:<你的用户名>/<仓库名>.git  # SSH 方式
   # 若用 HTTPS 方式：git remote add origin https://github.com/<你的用户名>/<仓库名>.git
   

4. 提交并推送代码：

   
   git add .  # 添加所有文件到暂存区
   git commit -m "Initial commit: upload web files"  # 提交代码
   git branch -M main  # 确保主分支是 main（GitHub 默认分支）
   git push -u origin main  # 推送到 GitHub 仓库
   

步骤 3：开启 GitHub Pages 服务

1. 进入仓库页面，点击顶部的 Settings（设置）

2. 在左侧菜单栏找到 Pages（往下滑，在「Code and automation」分类下）

3. 在「Build and deployment」区域：

   • Source（来源）：选择 Deploy from a branch（从分支部署）

   • Branch（分支）：选择 main（或你的代码所在分支，比如 master），然后选择根目录 /（如果代码在 docs 文件夹，选 /docs）

   • 点击 Save 保存设置

4. 保存后页面会刷新，稍等几秒，在「GitHub Pages」区域会显示你的网页访问地址（比如 https://testuser.github.io/）

步骤 4：访问你的网页

复制步骤 3 中显示的地址，粘贴到浏览器访问即可。注意：首次部署可能需要 1-5 分钟生效，若访问不了，先等待再刷新。

三、进阶配置（可选）

1. 自定义域名

如果你有自己的域名（比如 www.yourname.com），可以绑定到 GitHub Pages：

1. 在仓库 Settings → Pages → Custom domain 中输入你的域名（比如 www.yourname.com），点击 Save

2. 去你的域名服务商（比如阿里云、腾讯云）配置 DNS 解析：

   • 添加 CNAME 记录：主机记录 www，记录值 <你的用户名>.github.io

   • 添加 A 记录：主机记录 @，记录值填 GitHub Pages 的 IP（可查 GitHub 官方文档，比如 185.199.108.153 等）

3. 等待 DNS 解析生效（通常 10 分钟-2 小时），即可用自定义域名访问。

2. 自动部署（GitHub Actions）

如果你的前端项目需要构建（比如 Vue/React/Next.js 项目），可以用 GitHub Actions 自动构建并部署：

1. 在仓库中创建 .github/workflows/deploy.yml 文件

2. 粘贴以下示例配置（以 Vue 项目为例）：

   
   name: Deploy to GitHub Pages
   on:
     push:
       branches: [main]  # 推送到 main 分支时触发
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
             node-version: 20
         - name: Install dependencies and build
           run: |
             npm install
             npm run build
         - name: Deploy to GitHub Pages
           uses: peaceiris/actions-gh-pages@v4
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./dist  # Vue 项目构建后的目录
   

3. 推送该文件后，GitHub 会自动运行 Action，完成构建和部署。

四、常见问题解决

1. 访问 404：

   • 检查仓库名是否符合规则（个人主页必须是 <用户名>.github.io）

   • 检查 index.html 是否在根目录，文件名是否小写

   • 检查 Pages 设置中的分支和目录是否正确

2. 样式/图片加载失败：

   • 前端代码中尽量用相对路径（比如 ./css/style.css），避免绝对路径（比如 /css/style.css，项目页面会找不到）

3. 部署后内容没更新：

   • 等待 1-5 分钟（GitHub Pages 有缓存）

   • 强制刷新浏览器（Ctrl+F5 / Cmd+Shift+R）

---

总结

1. 核心规则：GitHub Pages 仅支持静态页面，个人主页仓库名必须是 <用户名>.github.io，项目页面访问地址带仓库名。

2. 关键步骤：创建符合规则的仓库 → 上传前端代码 → 开启 Pages 服务（选择分支/目录）→ 访问生成的地址。

3. 注意事项：用相对路径避免资源加载失败，首次部署有缓存，耐心等待生效；动态功能需用前端纯静态实现（如 JS 调用 API）。