Will.liu把个人简历、作品集或者博客部署到公网上，让朋友用一个链接就能访问，很多人第一反应是买云服务器、配Nginx、折腾域名备案，整套流程下来钱包和心态都受考验。其实用 GitHub 仓库部署个人主页网页，是开发者圈子里最省事的方案：仓库本身就托管页面代码，Pages 服务负责构建和发布，全程免费，还自动送 HTTPS 证书，省掉了服务器运维这一大摊事儿。这篇内容是我多次实际部署踩坑后的经验整理，从账号准备、文件规范、仓库创建、发布配置到自定义域名，把完整操作流程从头到尾讲清楚。适合完全没建过站的新手，也适合想快速搭一个干净个人页面的老手直接参考。
1. 部署方案的整体设计与思路拆解
1.1 为什么选 GitHub 仓库做个人主页，而不是自己买服务器
GitHub Pages 是平台提供的免费静态网页托管服务，它会把仓库里的静态文件变成人人都能访问的网站。所谓静态文件，就是不需要服务器端实时计算、每次请求都返回固定内容的文件，HTML、CSS、JS、图片都属于这一类。个人主页、简历、开源项目展示页、轻量级技术博客，都是典型的静态场景。
把网页放到自己服务器上也能跑，但我个人不建议为了一个个人主页去做这件事。一台轻量云服务器一年要几百上千块，还要配防火墙、装 Nginx、处理 HTTPS 证书定期续期，遇到服务器宕机、磁盘满了都得自己扛，这对只想展示资料的人来说负担太重。Git 仓库托管的方式把这些都封装好了：你在本地写好文件，推到仓库，构建和分发平台自动完成，域名证书也是自动签发，你最需要关注的只是内容本身。
我打个比方你就明白了。GitHub Pages 就像一个帮你开好店面、通好水电、请好物业的商场，你只需要把货架上的商品也就是网页文件摆好，商场就帮你把场地对外开放。如果你要自建服务器，相当于自己租地、盖楼、拉电、请保安，为一场小型展览搞一整栋楼，性价比非常低。所以只要不是做重交互的后台应用，个人部署选它就对了。
1.2 纯静态 HTML、Jekyll、Hexo 怎么选
在正式开始部署之前，先确定网页文件用什么方式生成，因为不同方式对应的目录结构和发布配置有差异。我见过很多人上来就套博客框架，结果把自己绕晕。这里给一张对比表，你再选也不迟。
| 方案 | 学习成本 | 适用人群 | 推荐场景 |
|---|---|---|---|
| 纯静态 HTML | 最低 | 所有新手 | 个人简历、作品集、单页介绍 |
| Jekyll | 中 | 想写博客但不想太复杂 | 个人博客、文档站 |
| Hexo | 较高 | 愿意折腾 Node.js 生态 | 深度定制博客、主题丰富的站点 |
如果你的网站只有几个页面，我强烈建议直接写纯静态 HTML。不要觉得这种方案太原始，GitHub Pages 本身每天托管大量纯静态页面，结构简单意味着出问题的环节少。Jekyll 是平台原生支持的博客框架，你在仓库里放 Markdown 文件，平台自动把它们编译成 HTML，门槛在于要理解主题、布局、变量的概念，偶尔还会因为版本和插件问题报错。Hexo 则是先把 Markdown 在本地编译成 HTML 再推送，优点是灵活漂亮，缺点是本地要装 Node.js 环境，构建流程多一步，适合你想认真经营博客的情况。
从复用和维护角度看，纯静态 HTML 最容易被未来接手的人读懂，你三个月后回来看，也知道改了哪个文件就是改了哪个页面。博客框架一旦升级主版本，主题和写法可能都要跟着调整。我自己的个人主页最终就回归成简单的 HTML 加一点 CSS，不是因为别的框架不好，而是这个场景下没必要引入额外复杂度。
1.3 部署后的效果边界与适用场景
部署完成后，你得到的是一组固定 URL，比如 https://用户名.github.io 或者 https://用户名.github.io/仓库名/。它可以承载你的简历、联系方式、项目展示、个人博客，甚至可以做一个简单的工具页。需要注意的是它不支持服务端脚本，比如 PHP、Python 后端、数据库读写都跑不了。如果你需要用户提交表单后写进数据库这类功能，得另找第三方后端服务，或者换成有服务器的方案，这些边界在开始之前就想清楚，免得做到一半才发现路线不对。
另外，个人主页是一个很强的身份标识。域名里带上你的名字，发给面试官、客户、合作方，都比甩一个网盘链接靠谱得多。GitHub 仓库本身就自动保留历史版本，你改坏了某个页面，随时能回退到之前的版本，这是普通 FTP 建站做不到的。单就这个版本管理能力，就足够成为选择它的理由。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 动手前的准备：账号、Git 与网页文件规范
2.1 注册 GitHub 账号时要注意什么
第一步是注册一个 GitHub 账号，注册页面会让你填用户名、邮箱和密码。用户名需要认真想，因为个人主页的默认访问地址是 用户名.github.io，这个用户名也会出现在你所有开源仓库的地址里。它类似于一个全网公开的昵称，注册之后想改名可以，但旧链接会失效，涉及的项目很多时会很麻烦，所以一开始就想清楚。
注册过程可能会要求验证邮箱，点一下验证邮件里的链接即可。一个邮箱只能关联一个账号，如果你以前注册过，建议直接找回密码，不要为了部署主页去反复注册小号。早年间还有人用同一个手机号注册多个账号，后来平台加强了验证，多账号管理成本变高，没必要。
注册完成后，顺手把头像、个人简介填上，尤其是介绍栏，写上你是做什么的、关注什么方向，这会让主页更有温度。很多人忽略这个细节，其实个人主页站点和 GitHub 账号主页是两套页面，前者靠你上传的网页文件，后者靠账号设置，两者可以配合使用，但不冲突。
2.2 安装并初始化 Git
上传网页文件有很多种方式，但不管用哪一种，本地装一个 Git 都值得。Git 是版本管理工具，官方叫分布式版本控制系统，通俗讲，它能把你文件夹里的每一次修改都记录成一个快照，随时可以回溯。去官网下载对应操作系统的安装包，Windows 用户在安装时一路默认即可，macOS 用户直接安装官方安装包就能获得。
装好后打开终端或命令提示符，输入 git --version，能看到版本号就说明装好了。接下来设置身份信息，这样每次提交代码时，平台才知道是谁在提交：
bash复制git config --global user.name "你的用户名"
git config --global user.email "你注册GitHub时用的邮箱"
user.email 建议和 GitHub 注册邮箱保持一致，从本机提交的记录就能直接关联到你的账号，以后统计贡献记录也方便。如果配置过程中填错了，重新执行一次同样的命令覆盖即可，不需要额外卸载什么。
2.3 网页文件准备：目录结构与命名规范
接下来准备你要部署的内容。本地建一个干净的项目文件夹，比如 my-site，里面放网页文件。固定入口文件必须叫 index.html，这是浏览器访问目录时默认加载的文件，相当于一栋楼的单元门牌，没有它，访客只会看到 404。推荐目录结构如下：
code复制my-site/
├── index.html
├── css/
│ └── style.css
├── js/
│ └── main.js
├── images/
│ └── avatar.png
└── CNAME （有自定义域名时才放）
文件名的大小写也需要统一，GitHub Pages 的运行环境对大小写敏感。你在 Windows 本地写了一个 style.css，上传到仓库里却变成了 Style.css，页面里引用 style.css 就找不到。稳妥做法是全程统一小写字母加连字符，例如 hero-section.css、nav-logo.png，这样可以完全避免大小写带来的坑。
HTML 里引用 CSS、图片、JS 时，尽量用相对路径，不要用 /css/style.css 这种以斜杠开头的绝对根路径。相对路径的意思是相对于当前文件所在位置的路径，写成 css/style.css 或者 ./css/style.css 更保险。原因我放到后面常见问题里详细讲，你只要先记下这个习惯就好。网页写完后，本地用浏览器打开 index.html 检查一遍，确认没错再进入部署步骤。
3. 完整部署流程实操
3.1 创建符合规则的仓库
登录 GitHub 网页版，点右上角加号选择 New repository。仓库名填写 你的用户名.github.io，注意大小写最好和用户名保持一致，例如你的用户名是 zhangsan，仓库名就是 zhangsan.github.io。这是平台约定好的特殊名字，只有满足这个命名规则的仓库会被当作个人主页站点处理，访问域名不用带额外路径。
可见性选择 Public，这样任何人都能通过链接访问。如果你是付费用户也可以选 Private 后再单独配置 Pages，但日常个人主页建议直接 Public，省心且更符合开源分享的调性。下方不要勾选 Add a README file，因为我们已经有自己的网页文件，如果勾选了，第一次推送时容易产生多余分支和冲突；可以先在本地把 README 写好再推上去。
创建完成后你会得到一个空仓库，页面会显示远程仓库地址，常见两种：HTTPS 形式如 https://github.com/用户名/用户名.github.io.git，SSH 形式如 git@github.com:用户名/用户名.github.io.git。第一次使用建议用 HTTPS 地址，按提示输入账号密码或访问令牌即可；SSH 需要额外生成密钥，对新手多一步概念理解，以后熟练了再切换也不迟。
3.2 上传网页文件的三种方式
第一种最直观：在仓库页面点击 Add file 选择 Upload files，把本地文件夹里的文件拖拽到上传区域，写好提交说明后点 Commit changes。适合文件数量少、不需要频繁更新的情况。缺点是拖拽上传偶尔会出现目录结构错乱，尤其是深层嵌套的文件夹，我见过上传后 CSS 文件跑到奇怪位置的情况，小项目可用，复杂度上来后就别依赖它。
第二种是命令行。在项目文件夹中打开终端，依次执行初始化、提交、关联远程仓库、推送这几步。我贴一段可以直接用的命令序列：
bash复制git init
git add .
git commit -m "feat: 初始化个人主页"
git branch -M main
git remote add origin https://github.com/用户名/用户名.github.io.git
git push -u origin main
注意 git add . 会把当前目录所有文件加入暂存区，所以在建仓库之前最好先写好 .gitignore 文件，把不需要上传的内容排除掉，比如 mac 下的 .DS_Store、编辑器缓存文件、node_modules 依赖目录。没有这个文件其实也能推，但仓库会变得很脏，之后每次改动都可能带着一堆无意义文件。
第三种是 GitHub Desktop 图形客户端。下载安装后用账号登录，选择 Add local repository 定位到本地项目文件夹，然后 Commit to main 再 Push origin 即可。我一般推荐纯新手用这种方式，因为每一步都有界面提示，push 前还能清楚看到改动了哪些文件。缺点是多装一个软件，而且对 Git 内部原理始终隔着一层，但我认为先跑通完整流程更重要，熟练了再退回命令行也来得及。
3.3 开启 Pages 服务并验证访问
文件推送成功后，进入仓库的 Settings 页面，在左侧菜单找到 Pages。Source 区域选择 Deploy from a branch，Branch 下拉框选择 main 或 master，取决于你刚才推送的分支名，目录通常保持 /root 即可，点击 Save 保存。稍等片刻页面会刷新，出现一行 Your site is published at https://用户名.github.io，这个地址就是你个人主页的正式入口。
很多人会问为什么保存后马上访问还是 404。因为平台需要时间把文件拉取出来、执行可能的构建流程、再发布到节点上，这个过程从几十秒到几分钟不等，首次创建有时更长。建议不要反复刷新干等，直接切到仓库顶部的 Actions 标签页，你会看到一次名为 Pages build and deployment 的工作流正在运行，等它旁边出现对勾，访问基本就通了。
如果 Actions 里显示失败，点开失败记录能看到日志，常见原因包括文件路径里有非法字符、仓库根目录缺少 index.html、Jekyll 构建报错。这时候需要回到本地改正文件再重新 push。我特别喜欢这套机制的一点是，每一次 push 都会触发一次新的部署，更新网页就像发邮件一样自然。
3.4 绑定自定义域名
默认地址 用户名.github.io 已经能用，但如果你有自己的域名，绑定它会让页面更正式。域名解析是另一套体系，你在域名服务商的控制台添加记录，让域名指向平台。最简单的方式是用 CNAME 记录，把 www 开头的子域名指向 用户名.github.io。如果你的域名服务商支持根域名的 CNAME 扁平化功能，也可以直接把主域名做 CNAME；如果不支持，就用 A 记录把主域名指向平台公布的四个 Pages IP 地址，一般是 185.199.108.153、185.199.109.153、185.199.110.153、185.199.111.153，建议四个都配上。
然后在仓库 Settings 的 Pages 页面，在 Custom domain 一栏填入你的自定义域名并保存。平台会先验证一遍这个域名是否真的解析到了它，有时候会要求你按提示添加一条 TXT 记录来证明域名是你的，按提示操作即可。等解析生效后，回到同一页面勾选 Enforce HTTPS，平台会自动申请并续期 HTTPS 证书。证书下发通常需要一些时间，中间可能出现证书警告，属正常现象，等十几分钟再刷新。
还有一个细节：在仓库根目录放一个名为 CNAME 的纯文本文件，内容只写一行你的自定义域名，例如 www.example.com，不要有其他字符。这样即使以后在网页版设置里不小心清空了自定义域名，文件还在，重新推送也能恢复。我个人习惯在本地项目里就把这个文件维护好，把它当普通源码一起管理。
4. 常见问题与排查技巧
4.1 访问出现 404 的排查清单
这是出现频率最高的问题。按顺序检查三件事：第一，仓库名是否严格是 用户名.github.io，GitHub 用户名本身不能包含大写字母，仓库名建议与用户名保持一致，不要出现下划线或额外字符，否则 Pages 的识别规则可能把你带到别的路径；第二，分支和目录是否选择正确，如果你 push 到 main，发布源却选了 master，仓库里肯定找不到可部署文件；第三，仓库根目录是否存在 index.html。如果这三项都对，最后再等两分钟重新加载，因为发布队列延迟也是常态。
还有一个隐藏情况是分支名不统一。本地新建仓库时，老版本 Git 默认分支叫 master，新版本叫 main；如果你本地一直用 master，推送到远端后仓库里可能出现 main 和 master 两个分支，但发布源却还指着 main，页面自然一直是旧的或者 404。所以我建议在推送前执行 git branch -M main 这行命令，强制把本地分支改名为 main，跟新项目默认保持一致，省去后面纠结。
4.2 页面能打开但样式错乱、图片消失
这通常是资源路径问题。举个例子，你的 index.html 在仓库根目录，CSS 文件在 css 目录，如果你在 HTML 里写的是 /css/style.css，那么这个路径是从域名根开始解析的。如果站点部署在特殊命名的个人主页仓库，解析成 https://用户名.github.io/css/style.css 恰好是对的；但如果仓库名不是特殊命名，页面实际地址是 https://用户名.github.io/仓库名/，根路径就变成了 https://用户名.github.io/css/style.css，自然找不到。所以最稳妥的写法永远是 css/style.css 这样的相对路径，无论部署在哪一层目录都不会错。
另一个常见原因是文件大小写不一致，前面说过 Pages 环境区分大小写。本地图片叫 avatar.png，引用写成 Avatar.png，本地浏览器因为系统忽略大小写可能正常显示，部署后就是红叉。建议在上传前用命令行检查一遍文件名，统一成小写。
样式错乱还有一个我踩过的坑：CSS 文件本身没问题，但因为 HTML 头部漏写了 viewport 等 meta 标签，导致页面在手机和桌面上的表现完全不同，看起来像没加载样式。不过这个和部署关系不大，一般你会发现本地打开也是乱的，所以部署前本地预览这一步真的不能省。
4.3 push 成功但线上不是最新版
推送成功之后线上还是旧页面，先确认 Actions 里的部署工作流真的跑完了，光有 push 成功不等于部署成功。如果看到工作流日志里出现 error，常见原因是文件路径含空格或中文名，平台在构建阶段会报错；也有人因为引用了不存在的资源导致页面部分失败，但工作流仍然显示成功，这种情况需要打开浏览器开发者工具看具体请求。
浏览器缓存也可能骗你。HTML 文件换了内容，但浏览器把旧版本存在本地，强制刷新 Ctrl+Shift+R 或者用无痕窗口打开就能看到最新内容。节点缓存通常不会太久，多数情况下清一次浏览器缓存就解决。如果你改完立即打开发现还是旧版，别急着重新 push，先做这两个检查。
最后提醒一点：GitHub Pages 默认把主分支当发布源时，每次 push 都会触发部署工作流。若你的仓库是大型项目、历史提交非常多，第一次部署可能较慢，但之后的增量推送都很快。尽量保持仓库干净，不要在仓库里放超大文件，Pages 只适配静态网站场景，放一个压缩包进去既浪费也不会有任何效果。
4.4 关于 .nojekyll 文件与构建过程的避坑心得
我在第 1 节说过，Jekyll 是平台原生支持的博客框架。这带来一个副作用：只要仓库根目录存在 _config.yml，平台就会默认用 Jekyll 去构建整个项目。而 Jekyll 在构建时会自动忽略所有以下划线开头的文件和目录，比如你的资源目录如果叫 _images、_files，部署后会发现这些资源集体消失；还有它要求目录结构符合 Jekyll 约定，如果你只放了纯 HTML，某些路径会生成奇怪的结果。这不是页面写错了，而是构建器不理解你的项目。
解决办法是在仓库根目录放一个空文件 .nojekyll。名字的语义就是告诉平台：这个仓库不需要 Jekyll 构建，请把文件当普通静态文件直接发布。我写纯 HTML 项目时，每次都会第一时间创建这个文件，一行字符都不写，只占一个文件名。很多新手把网页推上去发现缺样式、缺图片，改了半天路径都没用，最后加一个 .nojekyll 就好，这个经验我用过很多次。
但要注意，如果你真的在用 Jekyll 主题写博客，就不要放 .nojekyll 文件，否则 Markdown 文件不会被编译成 HTML，访客会看到一堆原始文本甚至 403。这时候你应该去检查 _config.yml 里的 baseurl、theme、plugins 配置。判断自己属于哪种情况很简单：本地建站工具是纯 HTML 就是前者，用 Jekyll 命令或者依赖在线自动编译博客的就是后者，按场景决定文件去留。
部署这件事跑通一次之后，你会发现它的核心其实不是命令，而是一套稳定的文件组织习惯。我自己的个人主页从最初乱放文件名、踩遍 404 和样式丢失，到后来形成固定模板：项目根目录固定放 index.html、css 子目录、images 子目录、一个 .nojekyll 空文件，需要自定义域名时再加 CNAME 文件，每次更新就是本地改完 git add、commit、push 三步。这套流程后来帮我在十分钟内就上线过一个活动宣传页。如果你刚开始接触，别急着上博客框架，先用最简单的方式把个人主页跑起来，等你真正需要博客的排版能力时，再引入 Jekyll 或 Hexo 都不迟。最后再分享一个小技巧：把本地项目文件夹用 Git 管理起来远比直接在网页端传文件靠谱，因为你的发布历史、回滚能力、自动化部署全都建立在这之上，而这只是多敲几行命令而已。