GitHub Pages 静态网页部署指南：从上传 HTML 到用户通过链接访问

前言

很多前端小项目、个人主页、产品介绍页、在线简历、组件 Demo、技术文档，其实并不需要单独买服务器。

如果你的网页只是由这些文件组成：

HTML
CSS
JavaScript
图片
字体
静态资源

并且不需要后端运行环境，比如 Java、Node.js、PHP、Python 服务，那么它就很适合部署到 GitHub Pages。

部署成功后，用户可以直接通过类似下面的链接访问：

https://你的用户名.github.io/仓库名/

或者如果是个人主页：

https://你的用户名.github.io/

本文按教学方式展开：

GitHub Pages 是什么。
静态网页和后端服务有什么区别。
GitHub Pages 的两种部署方式。
纯 HTML 项目如何发布。
Vue、React、Vite 这类构建型项目如何发布。
发布后的访问链接规则。
常见 404、白屏、资源路径错误如何排查。

一、GitHub Pages 是什么

GitHub Pages 是 GitHub 提供的静态网站托管能力。

你把静态网站文件放到 GitHub 仓库中，并在仓库设置里开启 Pages，GitHub 就会把这些文件发布成一个可以公开访问的网站。

它适合部署：

个人主页
项目官网
在线简历
HTML/CSS/JS 小作品
前端组件 Demo
技术文档
博客静态页面
Vue、React、Vite、Hexo、Hugo 等构建后的静态文件

它不适合部署：

Java 后端服务
Spring Boot 应用
Node.js API 服务
PHP 动态网站
需要数据库连接的服务端程序
WebSocket 后端服务

原因很简单：GitHub Pages 托管的是静态文件，不运行你的后端进程。

二、什么是静态网页

静态网页指的是浏览器拿到文件后就能直接渲染的网页。

例如：

index.html
style.css
main.js
logo.png

浏览器访问 index.html，再加载 CSS、JS、图片，页面就能显示。

它不需要服务器动态计算页面内容。

对比一下：

类型	是否适合 GitHub Pages	原因
普通 HTML/CSS/JS	适合	直接发布静态文件
Vue/React 构建产物	适合	构建后是静态文件
Vite 项目源码	不能直接发布	需要先 build
Spring Boot jar	不适合	需要 Java 进程
Node.js Express API	不适合	需要 Node 进程
PHP 网站	不适合	GitHub Pages 不运行 PHP

所以判断标准是：

最终能不能变成一批静态文件。

如果能，就可以部署到 GitHub Pages。

三、GitHub Pages 的两种发布方式

GitHub Pages 常见发布方式有两种。

方式一：从分支发布

这是最简单的方式。

你把静态文件放在仓库某个分支的根目录，或者 /docs 目录，然后在 Settings 里选择发布源。

适合：

纯 HTML/CSS/JS 项目
不需要构建的项目
简单个人主页
简单项目说明页

例如仓库结构：

my-site
├── index.html
├── style.css
└── main.js

开启 Pages 后，GitHub 直接发布这些文件。

方式二：通过 GitHub Actions 发布

如果项目需要构建，就应该使用 GitHub Actions。

适合：

Vue
React
Vite
Angular
Hexo
Hugo
Astro
Docusaurus
其他需要 npm run build 的项目

例如 Vite 项目源码结构：

my-vite-app
├── package.json
├── index.html
├── src
│   └── main.js
└── vite.config.js

这个项目不能直接把源码目录当成 Pages 发布源。正确流程是：

拉取代码
安装依赖
执行 npm run build
生成 dist
把 dist 发布到 GitHub Pages

这个过程适合交给 GitHub Actions 自动完成。

四、访问链接规则

GitHub Pages 有两种常见站点类型。

4.1 用户或组织站点

仓库名必须是：

username.github.io

发布后访问：

https://username.github.io/

例如 GitHub 用户名是 octocat，仓库名就是：

octocat.github.io

访问地址：

https://octocat.github.io/

这种方式适合个人主页。

4.2 项目站点

仓库名可以是任意项目名，例如：

my-demo

发布后访问：

https://username.github.io/my-demo/

例如：

https://octocat.github.io/my-demo/

大多数项目 Demo 都属于这种方式。

五、准备一个最简单的静态网页

先从最简单的纯 HTML 项目开始。

新建一个文件：

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>我的第一个 GitHub Pages 网站</title>
  <style>
    body {
      margin: 0;
      font-family: Arial, "Microsoft YaHei", sans-serif;
      background: #f5f7fb;
      color: #222;
    }

    .page {
      max-width: 760px;
      margin: 80px auto;
      padding: 32px;
      background: #fff;
      border: 1px solid #e5e7eb;
      border-radius: 8px;
    }

    h1 {
      margin-top: 0;
    }

    p {
      line-height: 1.8;
    }
  </style>
</head>
<body>
  <main class="page">
    <h1>Hello GitHub Pages</h1>
    <p>这是我的第一个通过 GitHub Pages 发布的静态网页。</p>
    <p>只要仓库配置正确，别人就可以通过链接访问这个页面。</p>
  </main>
</body>
</html>

关键点：

入口文件必须叫 index.html、index.md 或 README.md 之一。

最常用的是 index.html。

六、方式一：从分支发布纯静态网页

6.1 创建 GitHub 仓库

github-pages-demo

如果使用免费账号，并希望公开访问，建议仓库使用 public。

6.2 上传网页文件

把下面文件上传到仓库根目录：

index.html

如果有样式和脚本，也可以是：

index.html
style.css
main.js
assets/logo.png

注意入口文件要在发布目录的顶层。

如果你选择从仓库根目录发布，index.html 就要在根目录。

如果你选择从 /docs 目录发布，结构应该是：

docs
└── index.html

6.3 开启 GitHub Pages

进入仓库页面：

Settings -> Pages

在 Build and deployment 中：

Source: Deploy from a branch
Branch: main
Folder: / root

然后点击 Save。

等待 GitHub 构建和部署完成。

6.4 访问页面

项目站点访问地址通常是：

https://username.github.io/github-pages-demo/

如果 GitHub 用户名是 zhangsan，仓库名是 github-pages-demo，访问地址就是：

https://zhangsan.github.io/github-pages-demo/

GitHub 官方文档说明，发布后可能需要几分钟才生效。实际使用中，第一次开启 Pages 后等 1 到 10 分钟是正常的。

七、方式二：用 GitHub Actions 发布 Vite/React/Vue 项目

很多前端项目不是直接写一个 index.html，而是用 Vite、React、Vue 开发。

这类项目通常需要先构建：

npm install
npm run build

构建后会生成：

dist

真正要发布到 GitHub Pages 的是 dist 目录，而不是源码目录。

7.1 Vite 项目需要注意 base

如果部署到项目站点：

https://username.github.io/repository/

那么 Vite 项目要配置 base。

例如仓库名是：

github-pages-demo

vite.config.js：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/github-pages-demo/'
})

React 项目使用 Vite 时也类似：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/github-pages-demo/'
})

为什么要配置 base？

因为项目站点不是部署在根路径 /，而是部署在：

/github-pages-demo/

如果不配置，页面可能能打开，但 CSS 和 JS 会请求到错误路径，导致白屏。

7.2 配置 GitHub Pages 使用 Actions

进入仓库：

Settings -> Pages

在 Build and deployment 中：

Source: GitHub Actions

保存。

7.3 新增 Actions 工作流

创建文件：

.github/workflows/deploy-pages.yml

内容：

name: Deploy static site to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

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

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

这个工作流做了几件事：

1. main 分支有 push 时触发
2. 拉取仓库代码
3. 安装 Node.js
4. 安装依赖
5. 执行 npm run build
6. 上传 dist 作为 Pages artifact
7. 部署到 GitHub Pages

7.4 查看部署结果

提交代码后，进入：

Actions

查看工作流是否成功。

成功后，再进入：

Settings -> Pages

可以看到 GitHub Pages 给出的访问地址。

也可以直接访问：

https://username.github.io/repository/

八、发布后为什么会 404

GitHub Pages 404 是最常见的问题。

常见原因如下。

8.1 Pages 没开启

检查：

Settings -> Pages

确认已经选择：

Deploy from a branch

或者：

GitHub Actions

8.2 没有入口文件

GitHub Pages 需要入口文件。

常见入口文件：

index.html
index.md
README.md

如果发布目录里没有这些文件，就可能 404。

8.3 文件放错目录

如果 Pages 配置的是：

main branch /docs

那么入口文件应该是：

docs/index.html

如果你放在根目录：

index.html

就不会被 /docs 发布源识别。

8.4 访问地址写错

用户站点：

https://username.github.io/

项目站点：

https://username.github.io/repository/

不要把项目站点误写成：

https://username.github.io/

除非你的仓库名就是 username.github.io。

8.5 刚发布，还没生效

GitHub Pages 发布不是瞬间完成。

如果刚开启 Pages 或刚 push，可以等几分钟。

如果超过十几分钟还不生效，再检查 Actions 和 Pages 设置。

九、为什么页面打开是白屏

白屏通常不是 Pages 没发布，而是资源路径错了。

9.1 JS 或 CSS 404

打开浏览器开发者工具，看 Network。

如果看到：

/assets/index-xxx.js 404
/assets/index-xxx.css 404

说明资源路径不对。

对于项目站点：

https://username.github.io/repository/

资源路径应该带上：

/repository/

Vite 项目通常通过 base 解决：

export default defineConfig({
  base: '/repository/'
})

9.2 路由刷新 404

React Router 或 Vue Router 如果使用 history 模式，直接刷新子路由可能 404。

例如：

https://username.github.io/repository/about

GitHub Pages 会去找真实文件：

/repository/about

但这个文件不存在，于是 404。

解决思路：

使用 hash 路由。
为静态站点做 404 fallback。
使用支持 SPA rewrite 的托管平台，比如 Vercel、Netlify。

GitHub Pages 对复杂 SPA rewrite 支持有限，所以新手项目推荐先用 hash 路由。

示例：

https://username.github.io/repository/#/about

十、为什么 Actions 构建失败

如果使用 GitHub Actions 发布，失败原因通常在 Actions 日志里。

常见问题：

10.1 package-lock.json 不存在

工作流里用了：

npm ci

但仓库没有 package-lock.json，会失败。

解决：

npm install

生成 package-lock.json 后提交。

或者把工作流改成：

- name: Install dependencies
  run: npm install

生产项目更推荐提交 lock 文件并使用 npm ci。

10.2 build 命令不存在

检查 package.json：

{
  "scripts": {
    "build": "vite build"
  }
}

如果没有 build 脚本，下面命令会失败：

npm run build

10.3 dist 目录名称不对

工作流里写的是：

path: dist

但有些框架输出目录可能是：

build
out
public

要按实际构建结果修改。

例如 Create React App 常见输出目录是：

path: build

十一、私有仓库能不能发布

GitHub Pages 的可用范围和仓库可见性跟账号计划有关。

对于免费账号，公开仓库使用 GitHub Pages 最常见。某些付费计划或组织计划支持私有仓库发布 Pages。

但要注意一个重要点：

GitHub Pages 网站发布后是可通过互联网访问的。

即使仓库是私有的，只要 Pages 站点发布到了公网，就不要在网页里放敏感数据。

不要发布：

密钥
token
内部接口地址
私有配置
未公开的业务数据
用户隐私数据

十二、自定义域名

GitHub Pages 默认域名是：

username.github.io

也可以绑定自己的域名，例如：

www.example.com

大致步骤：

在 GitHub Pages 设置里填写 Custom domain。
在域名 DNS 服务商处配置 CNAME 或 A 记录。
等待 DNS 生效。
开启 Enforce HTTPS。

如果只是学习和发布 Demo，不需要一开始就绑定自定义域名。先用默认 github.io 域名即可。

十三、完整流程总结

纯 HTML 项目

1. 创建 GitHub 仓库
2. 上传 index.html
3. Settings -> Pages
4. Source 选择 Deploy from a branch
5. Branch 选择 main 和 / root
6. 等待发布完成
7. 访问 https://username.github.io/repository/

Vite/React/Vue 项目

1. 确认 npm run build 能正常生成 dist
2. 如果是项目站点，配置 base: '/repository/'
3. Settings -> Pages -> Source 选择 GitHub Actions
4. 新增 .github/workflows/deploy-pages.yml
5. push 到 main
6. 在 Actions 查看构建和部署结果
7. 访问 https://username.github.io/repository/

十四、实践检查清单

发布前检查：

仓库是否已经 push 到 GitHub
是否有入口文件 index.html
Pages 发布源是否配置正确
项目站点路径是否包含仓库名
Vite/React/Vue 项目是否执行了 build
构建输出目录是否和 Actions 配置一致
是否配置了正确的 base
页面里是否包含敏感信息

发布后检查：

Settings -> Pages 是否显示访问地址
Actions 是否执行成功
访问链接是否正确
Network 里 CSS/JS 是否 404
子路由刷新是否 404
手机端访问是否正常

总结

GitHub Pages 的核心价值是：

把 GitHub 仓库中的静态文件发布成一个可公开访问的网站。

如果是简单 HTML 页面，直接用分支发布即可。

如果是 Vue、React、Vite 这类需要构建的项目，推荐使用 GitHub Actions：先构建，再部署构建产物。

记住三个关键点：

1. GitHub Pages 只能托管静态文件，不运行后端服务。
2. 项目站点访问路径是  https://username.github.io/repository/ 。
3. 构建型前端项目要注意 base 路径和构建输出目录。

掌握这三点，大多数 GitHub Pages 部署问题都能定位清楚。

参考资料

GitHub Docs：Configuring a publishing source for your GitHub Pages site
https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
GitHub Docs：Creating a GitHub Pages site
https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
GitHub Docs：Quickstart for GitHub Pages
https://docs.github.com/en/pages/quickstart

posted @ 2026-07-27 09:18 松鼠航阅读(2) 评论(0) 收藏举报

刷新页面返回顶部

松鼠航

GitHub Pages 静态网页部署指南：从上传 HTML 到用户通过链接访问

GitHub Pages 静态网页部署指南：从上传 HTML 到用户通过链接访问

前言

一、GitHub Pages 是什么

二、什么是静态网页

三、GitHub Pages 的两种发布方式

方式一：从分支发布

方式二：通过 GitHub Actions 发布

四、访问链接规则

4.1 用户或组织站点

4.2 项目站点

五、准备一个最简单的静态网页

六、方式一：从分支发布纯静态网页

6.1 创建 GitHub 仓库

6.2 上传网页文件

6.3 开启 GitHub Pages

6.4 访问页面

七、方式二：用 GitHub Actions 发布 Vite/React/Vue 项目

7.1 Vite 项目需要注意 base

7.2 配置 GitHub Pages 使用 Actions

7.3 新增 Actions 工作流

7.4 查看部署结果

八、发布后为什么会 404

8.1 Pages 没开启

8.2 没有入口文件

8.3 文件放错目录

8.4 访问地址写错

8.5 刚发布，还没生效

九、为什么页面打开是白屏

9.1 JS 或 CSS 404

9.2 路由刷新 404

十、为什么 Actions 构建失败

10.1 package-lock.json 不存在

10.2 build 命令不存在

10.3 dist 目录名称不对

十一、私有仓库能不能发布

十二、自定义域名

十三、完整流程总结

纯 HTML 项目

Vite/React/Vue 项目

十四、实践检查清单

总结

参考资料

公告