企业官网建设流程全解析

前阵子接到一个小需求：把代号叫 Spade2 的 HTML 静态项目部署到 GitHub Pages 对外访问。原以为只是推一个仓库就完事，结果真正跑起来才发现，分支选择、相对路径、构建缓存、Actions 权限这些细节，哪一步没处理好都会让线上页面白屏。所以这次把完整流程和踩坑点都整理出来，让同样想用 GitHub Pages 部署 HTML 项目的朋友少走一点弯路。

如果你是刚接触 GitHub Pages，手里的项目也是纯 HTML、CSS、JS 的静态页面，这篇内容可以直接照着操作。如果你的项目用了 Vite、Webpack、React 这类构建工具，里面关于路径、部署分支、Actions 的内容同样适用，只需要在构建产物输出这一步做对应调整。

1. 部署前的准备与方案评估

1.1 为什么选择 GitHub Pages 而不是别的方式

Spade2 是一个纯静态页面项目，没有后端接口、没有数据库依赖，所有资源都是 html、css、js、图片。这类项目要对外展示，最理想的方式就是找个静态托管平台。GitHub Pages 的定位就是专门托管这类内容，最大的优势是免费、支持 HTTPS、可以和代码仓库放在一起管理，推送代码的同时就完成了发布。

有人可能会问，为什么不用其他平台？我当时的考虑很简单：代码已经在 GitHub 上，托管到 GitHub Pages 不需要额外的服务、不需要绑定银行卡，也不涉及单独的学习成本。尤其对个人项目、课程作业、简历页面、开源项目演示页来说，GitHub Pages 是最省心的方案。它自带的 HTTPS 证书也不需要手动配置，平台自动签发和维护。

还有一个隐藏好处：GitHub Pages 的访问地址很长一段时间内都很稳定。只要你仓库不删除，这个链接就不会失效，非常适合把演示链接写到简历、README、项目文档里长期挂着。

1.2 三种常见的部署路径对比

部署方式我梳理了一下，分三种：分支部署、Actions 部署、网页直传。三者适用的场景不同，实际操作时我是先用分支部署跑通，然后改成 Actions 方式，因为项目后续维护频率会变高。

我最终选的是 Actions 部署，因为 Spade2 后续可能需要加一个自动生成文档的步骤，而分支部署很难把“构建”和“发布”分开控制。如果只是为了快速把 HTML 页面放上去，直接用分支部署就够了，这一点后面会详细讲。

1.3 仓库准备与本地前提条件

动手部署前，先确认三件事。第一，本地装了 Git，并且已经配置好了全局用户名和邮箱。第二，有一个 GitHub 账号，注册时间够不够旧不重要，只要账号正常就行。第三，确认你的项目目录结构是清晰的，不要把 node_modules、临时文件这些无关内容推到仓库里。

你需要决定仓库名字。如果这个项目想用https://用户名.github.io/仓库名/这种地址访问，仓库名可以随意起，比如spade2-demo。如果你想用https://用户名.github.io/这种顶级路径访问，就必须把仓库名命名为用户名.github.io，这两种模式我建议一般项目用前者，方便管理多个演示项目。

我这次用的仓库名就是spade2-demo，项目代号 Spade2，整个部署过程都是基于这个假设展开的。后续所有 URL 示例也会以用户名.github.io/spade2-demo/作为基础路径来说明。

2. HTML 项目结构整理与本地校验

2.1 目录结构与相对路径的坑

Spade2 这个项目的目录结构比较简单，但越是简单的项目越容易在路径上栽跟头。很多人在本地双击 index.html 能看到页面，传上去却一堆 404，核心问题就出在“绝对路径”和“相对路径”的选择上。

先看一个典型翻车案例。假如你在index.html里写了这样一句引用：

<link rel="stylesheet" href="/css/style.css">

这个/css/style.css是绝对路径，浏览器会把它解析成“当前域名根目录下的 css/style.css”。本地双击打开时，根目录是你的磁盘某个分区，恰好能找到这个文件；部署到 GitHub Pages 项目站点后，项目的实际地址是https://用户名.github.io/spade2-demo/，此时/css/style.css就会去访问https://用户名.github.io/css/style.css，结果就是 404，样式丢失。

解决办法有两种。一种是把所有资源引用改成相对路径，比如href="css/style.css"或href="./css/style.css"，让浏览器基于当前页面路径去计算资源位置。另一种是用构建工具，在构建时把资源前缀改成项目的 base 路径，这属于后面进阶操作，这里先不展开。

要给这个坑一个直观结论：纯 HTML 项目，一律使用相对路径，不要用/开头的绝对路径。如果你项目里有 js 动态拼接 URL 的地方，比如fetch('/api/data.json')，也要改成fetch('api/data.json')。

2.2 本地用 HTTP 服务模拟线上环境

直接双击 index.html 打开页面，和线上真实环境的差异比你想象的大。比如文件协议下异步请求会被拦截，某些浏览器对通过 Ajax 加载本地 JSON 有跨域限制，还有些 JavaScript 的行为在 file:// 协议下表现不一样。所以部署前建议用本地 HTTP 服务预览一遍。

如果你电脑有 Python，在项目根目录打开终端执行：

python -m http.server 8080

然后浏览器访问http://localhost:8080/即可。

如果你熟悉 Node.js 环境，也可以用 npx 直接启动：

npx serve -l 8080 .

这一步最大的价值不只是看页面能不能打开，而是可以提前发现路径问题。因为在http://localhost:8080/下，浏览器解析相对路径的规则和线上 GitHub Pages 基本一致，只要这个环境页面正常，部署上去出路径问题的概率会大大降低。

2.3 GitHub Pages 的 URL 路径与资源引用规则

理解 GitHub Pages 的 URL 规则是整个部署过程的底层逻辑。假设你的 GitHub 用户名是username，仓库名是spade2-demo，部署成功后的首页地址是：

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

这个地址的组成可以理解成“用户名域名 + 仓库名路径”。需要注意的是，GitHub Pages 支持两种站点类型：用户站点的 URL 是https://username.github.io/，项目站点的 URL 是https://username.github.io/仓库名/。只有在仓库名是username.github.io时，页面才会被发布到根路径，其他仓库名都会作为子路径发布。

既然项目站点会挂在子路径下，所有资源引用就必须遵循这个规则。如果页面里有这样的代码：

<img src="images/logo.png">

实际请求的地址会是https://username.github.io/spade2-demo/images/logo.png，这是正确的。但如果写成：

<img src="/images/logo.png">

实际请求的地址就会变成https://username.github.io/images/logo.png，缺少了仓库名的路径段，必然 404。这就是为什么我一直强调相对路径，因为相对路径天然适配了子路径部署的场景。

3. 实操部署全流程

3.1 方式一：分支部署，最快看到线上效果

分支部署适合希望最快把页面发布出去、不关心构建过程的场景。整个操作拆解成四步。

首先在项目根目录初始化 Git 仓库并提交代码。

git init git add . git commit -m "init spade2 project" git branch -M main

接着在 GitHub 上创建一个空仓库，命名为spade2-demo，创建时不需要勾选任何初始化选项。然后在本地关联远端并推送。

git remote add origin git@github.com:username/spade2-demo.git git push -u origin main

第三步是进入 GitHub 仓库页面，点击 Settings，找到 Pages 菜单。在 Source 区域选择Deploy from a branch，Branch 选择main，目录选择/ (root)，然后点击 Save。这时候 GitHub 会自动开始构建部署，等一两分钟刷新页面就能看到效果。

这套流程跑一遍大约三分钟。我测试下来最常遇到的问题不是步骤不对，而是在第三步选分支时选错目录。有些项目把页面文件放在了docs/目录，这时就应该选/docs而不是/ (root)。所以你第一件事就是要搞清楚页面入口在哪一级目录，不要把路径选错。

3.2 方式二：GitHub Actions 自动部署

分支部署虽然快，但每次发布都要手动推代码。如果你的项目有构建步骤，或者希望以后发布更自动化，建议直接用 Actions。我后来把 Spade2 改成 Actions 部署后，每次更新只需要推源码，发布动作由工作流自动完成。

首先在项目根目录创建文件.github/workflows/deploy.yml，写入以下内容。

name: deploy-pages on: push: branches: - main workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: true jobs: deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - name: checkout uses: actions/checkout@v4 - name: setup-pages uses: actions/configure-pages@v5 - name: upload-artifact uses: actions/upload-pages-artifact@v3 with: path: '.' - name: deploy-pages id: deployment uses: actions/deploy-pages@v4

这个工作流的逻辑是：每次 push 到 main 分支，就自动把根目录下的所有文件打包上传，并且发布到 Pages。注意permissions部分必须保留，因为actions/deploy-pages需要申请写入 Pages 的权限，缺少这个配置会直接报权限错误。

工作流创建后，还需要把 Pages 的 Source 改成GitHub Actions。在仓库 Settings 里找到 Pages，Source 下拉框选择GitHub Actions，保存即可。之后每次 push，Actions 会自动执行部署，不需要再手动选分支。

如果你的项目有构建步骤，比如需要先执行npm run build，只需要在setup-pages之前加两步：

- name: setup-node uses: actions/setup-node@v4 with: node-version: '20' - name: build run: | npm ci npm run build

然后把upload-artifact里的path改成构建输出目录，比如dist。这样就能实现自动构建、自动发布一条龙。

3.3 方式三：网页直传，零命令操作

如果你不想用任何命令行工具，GitHub 的网页端也能完成上传。在仓库页面点击 Add file，选择 Upload files，把项目里的文件拖拽进去，输入 commit 信息，点击 Commit changes 提交，然后在 Pages 里选好分支即可。

这种方式的局限性在于，每次更新想替换某个文件都很麻烦。GitHub 网页端不支持批量覆盖同名文件，只能逐个文件夹进入、逐个文件替换。对于长期维护的项目，这种方式只适合应急。我第一次给 Spade2 做页面微调时用了一次网页直传，改到第三个文件就后悔了，最后还是老实回到 Git 命令行的方式。

4. 部署后的验证与高频排查

4.1 部署成功的判断标准

部署成功后访问https://username.github.io/spade2-demo/，应该能看到首页正常渲染。判断标准有两个层级：第一层是页面能打开，说明 HTML 已经被正确发布；第二层是样式、图片、脚本都能正常加载，说明所有资源路径都正确。第二步往往才是最需要花时间的环节。

如果你发现 HTML 正常打开但样式全无，优先检查资源路径是不是用了以/开头的绝对路径。如果你发现页面空白，而且浏览器控制台有报错，优先检查 JS 文件路径和引用的时机。如果你发现只有部分图片能显示，部分图片 404，先检查文件名大小写是否一致。GitHub Pages 的运行环境对文件名大小写敏感，而本地 Windows 环境大小写不敏感，很容易出现本地正常、线上白图的诡异问题。

4.2 高频问题速查表

排查问题时我的建议是：先看网络请求，再看控制台报错。打开浏览器开发者工具，切到 Network 面板，找到 404 的请求记录，直接看它的完整 URL，就能判断是路径少了仓库名还是文件名不对。这条经验能节省大量时间。

4.3 让 404 页面变得友好

GitHub Pages 对不存在的路径会返回统一 404 页面，样式是平台默认的，和站点风格不搭。想自定义 404 页面，只需要在项目根目录放一个404.html，GitHub Pages 会自动识别并使用它作为页面不存在时的展示页面。

这个404.html能做的事情其实比想象中多。它可以展示项目 Logo、友情提示、返回首页的链接，帮助访客在访问到错误链接时有路可退。我在 Spade2 的 404 页面里加了首页链接和邮箱联系方式，实测下来确实减少了误入死链后的流失。

还有一个进阶技巧：纯静态托管平台不支持服务端重写规则，但可以用 404.html 做前端路由适配。如果你的 HTML 项目里用了 history 模式的路由，刷新子路径时会 404，此时可以在 404.html 里写一段脚本，把当前路径映射回首页并同步路由状态。这个做法不算完美，但能在不换托管平台的前提下兼容 SPA 路由刷新，属于实用的小技巧。

5. 部署完成后的优化与扩展

5.1 绑定自定义域名与强制 HTTPS

默认的username.github.io/spade2-demo/域名虽然能用，但演示时不够干净。想绑自己的域名，步骤很简单：先去域名服务商把域名的 CNAME 记录指向username.github.io，然后在仓库 Settings 的 Pages 里找到 Custom domain，填入你的域名，点击 Save。GitHub 会自动验证域名归属，同时签发 HTTPS 证书，在证书生效前不要关闭强制 HTTPS 选项。

很多人会忽略一个细节：CNAME文件。如果你在 Pages 设置里填了自定义域名，GitHub 会在仓库根目录自动生成一个 CNAME 文件，内容是域名地址。这个文件一定要保留在仓库里。如果它被删了，GitHub 会在下次构建时把自定义域名重置掉。用了 Actions 部署后尤其容易踩这个坑，因为 Actions 的path: '.'默认会带上所有文件，只要你不删除它就没问题。如果构建目录是dist而 CNAME 放到了外部，就需要在构建脚本里把 CNAME 复制到dist里。

5.2 后续更新发布的推荐节奏

Spade2 部署稳定后，我给自己定的更新流程是这样：本地修改代码，在本地服务器预览确认，推送 main 分支，Actions 自动部署，等待约一分钟，刷新线上页面验证。整个过程不需要登录 GitHub 网页操作任何东西，发布和代码管理在同一个动作里完成。

如果你也用 Actions 方式，建议养成查看 Actions 运行状态的习惯。在仓库的 Actions 标签页里能看到每次部署的执行记录，绿色勾代表成功，红色叉代表失败。点开失败的记录能看到日志，错误信息会直接告诉你是哪一步出了问题。遇到失败了不要慌，日志就是最好的排查线索。

5.3 这个项目后续还能怎么扩展

Spade2 上线之后，我考虑过的几个扩展方向供你参考。一是给项目加一个自动生成的说明文档页面，用 Actions 在每次 push 时自动生成并部署到 Pages 的子目录。二是挂一个静态资源目录，把项目里常用的图片、PDF 资料也放在 Pages 里，方便外链引用。三是用 GitHub API 给项目做一个简单的访问量统计，虽然静态页面本身没有后端，但可以通过调用第三方统计服务实现类似效果。

这些扩展有一个共同思路：GitHub Pages 只是展示层，真正的自动化都能通过 Actions 工作流编排。当你把发布链路跑通之后，剩下的步骤都是在这个基础上叠加功能，本质依然是“源码推送触发自动构建+发布”。

这次部署 Spade2 让我印象最深的，是路径问题带来的连锁反应。本地双击 HTML 一切正常，推送上去样式全部丢失，调整引用路径后页面恢复，这个过程几乎每个用过 GitHub Pages 的人都会经历一遍。如果你正卡在某个环节出不去，回去检查一下项目里有多少以/开头的资源引用，大概率就是它的锅。换个角度说，正因为 GitHub Pages 极度简单，才更考验对 URL 路径和发布流程的基本功，这些东西一旦理解透了，后面用其他静态托管平台也能少踩很多坑。