如何使用 GitHub Pages 部署静态网站
如何使用 GitHub Pages 部署静态网站
GitHub Pages 是 GitHub 提供的免费静态网站托管服务，无需服务器、无需运维，提交代码即可自动部署。对于个人博客、项目文档、作品集展示等场景非常合适。
本文将从零开始，带你完成一个静态网站的部署。
一、GitHub Pages 简介
核心优势：
- 完全免费：无带宽限制、无存储费用
- 自动部署：推送代码后自动构建上线
- 自带 HTTPS：GitHub 自动签发 SSL 证书
- 支持自定义域名：可绑定自己的域名
- 全球 CDN：Fastly 提供全球加速
适用场景：
- 个人博客（Hexo、Hugo、VitePress 等）
- 项目文档 / 产品介绍页
- 纯前端作品集展示
- 静态 HTML / CSS / JS 页面
二、准备工作
| 项目 | 要求 |
|---|---|
| GitHub 账号 | github.com 免费注册 |
| Git | 本地安装 Git 用于推送代码 |
| 网站文件 | 准备好 HTML 文件或静态网站生成器项目 |
安装 Git
# Ubuntu / Debiansudo apt install git -y
# macOSbrew install git
# Windows# 下载：https://git-scm.com/download/win配置 Git 用户名和邮箱：
git config --global user.name "你的用户名"git config --global user.email "你的邮箱"三、创建仓库
方式一：用户/组织站点（推荐）
创建一个名为 用户名.github.io 的仓库，例如：
你的用户名.github.io仓库名必须与你的 GitHub 用户名完全一致，且为公开仓库（Public）。
方式二：项目站点
创建任意名称的仓库，GitHub Pages 会部署到 用户名.github.io/仓库名 路径下。
本文以用户站点为例，后续操作两种方式通用。
四、上传网站文件
1. 克隆仓库到本地
git clone https://github.com/你的用户名/你的用户名.github.io.gitcd 你的用户名.github.io2. 放入网站文件
在仓库根目录下创建 index.html 作为首页：
<!DOCTYPE html><html lang="zh-CN"><head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>我的网站</title> <style> body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; display: flex; justify-content: center; align-items: center; min-height: 100vh; margin: 0; background: #f5f5f5; } .card { background: white; padding: 40px; border-radius: 12px; box-shadow: 0 4px 20px rgba(0,0,0,0.1); text-align: center; } h1 { color: #333; margin: 0 0 10px; } p { color: #666; } </style></head><body> <div class="card"> <h1>部署成功！</h1> <p>我的第一个 GitHub Pages 网站</p> </div></body></html>3. 提交并推送
git add .git commit -m "初始化网站"git push origin main五、启用 GitHub Pages
1. 进入仓库设置
在 GitHub 仓库页面，点击 Settings → Pages。
2. 配置部署源
| 选项 | 说明 |
|---|---|
| Source | 选择 Deploy from a branch |
| Branch | 选择 main，目录选择 / (root) |
| 点击 Save |
3. 等待部署
保存后 GitHub 会自动开始构建部署，通常 1-2 分钟内完成。构建完成后，页面顶部会显示你的网站地址：
https://你的用户名.github.io4. 使用 GitHub Actions 部署（可选）
对于使用静态网站生成器（如 Hexo、Hugo、VitePress）的项目，推荐使用 GitHub Actions 自动构建部署。
在仓库根目录创建 .github/workflows/deploy.yml：
name: Deploy to GitHub Pages
on: push: branches: [main]
jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
# 如果你的项目需要构建（如 npm run build），在这里添加构建步骤 # - name: Build # run: | # npm install # npm run build
- name: Deploy uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./六、绑定自定义域名
1. 添加 DNS 记录
在你的域名 DNS 管理后台，添加以下记录：
| 类型 | 名称 | 值 |
|---|---|---|
| CNAME | www | 你的用户名.github.io |
| A | @ | 185.199.108.153 |
| A | @ | 185.199.109.153 |
| A | @ | 185.199.110.153 |
| A | @ | 185.199.111.153 |
如果使用 Cloudflare 托管 DNS，建议开启代理（橙色云朵）以获得 CDN 加速和 DDoS 防护。
2. 在仓库中配置域名
回到 GitHub 仓库 Settings → Pages，在 Custom domain 中输入你的域名，点击 Save。
GitHub 会自动在仓库根目录生成一个 CNAME 文件，同时申请 SSL 证书。
HTTPS 证书自动签发可能需要几分钟到几十分钟，耐心等待即可。勾选 Enforce HTTPS 强制使用 HTTPS。
七、常见问题排查
1. 网站 404
- 确认仓库名与用户名一致（
用户名.github.io） - 确认仓库为 Public（免费用户不支持 Private 仓库的 Pages）
- 确认
index.html在仓库根目录 - 检查 Settings → Pages 中 Branch 设置是否正确
2. 自定义域名无法访问
- 确认 DNS 记录已生效（可用
nslookup 你的域名检测） - 确认仓库中存在
CNAME文件，内容为你的域名 - 等待 DNS 缓存刷新（最长 48 小时，通常几分钟）
3. CSS / JS 不加载
- 检查资源路径是否正确（相对路径 vs 绝对路径）
- 如果使用自定义域名，确认路径中不包含仓库名
- 打开浏览器开发者工具查看 Network 面板定位 404 资源
4. 推送后网站未更新
- 检查 GitHub Actions 构建状态（Actions 标签页）
- 确认推送到了正确的分支（main）
- 等待构建完成（Settings → Pages 页面可见构建状态）
八、进阶技巧
使用静态网站生成器
推荐搭配以下工具，提升内容管理效率：
| 工具 | 特点 | 适合场景 |
|---|---|---|
| Hexo | 基于 Node.js，插件丰富 | 个人博客 |
| Hugo | Go 编写，构建极快 | 文档站、博客 |
| VitePress | Vue 驱动，简洁美观 | 技术文档 |
| Jekyll | GitHub Pages 原生支持 | 轻量博客 |
自定义 404 页面
在仓库根目录创建 404.html，访问不存在的页面时会自动展示：
<!DOCTYPE html><html><head><title>404 - 页面未找到</title></head><body> <h1>404</h1> <p>页面不存在，<a href="/">返回首页</a></p></body></html>多环境部署
利用 GitHub Actions 可以实现推送测试分支 → 部署预览站点、推送 main → 部署正式站点的流程。
九、结语
至此，你已经成功将网站部署到了 GitHub Pages。零成本、零运维、自动 HTTPS，对于个人项目来说是最省心的托管方案。
发布于 2026-07-08 by MinCiallo
支持与分享
如果这篇文章对你有帮助，欢迎分享给更多人或赞助支持！
评论区
音乐
暂未播放
赣公网安备36010802001440号