用 GitHub Pages 搭建个人网站主页是我见过“最省事但又有完整建站体验”的方案。不需要买服务器不需要维护后台你把 HTML、CSS、甚至一个 Markdown 文件放到 GitHub 仓库里GitHub 就会把仓库内容当成一个静态网站吐出来并且自带 HTTPS。这篇教程会把创建仓库、开启 Pages、修改页面、推送到生效的完整流程拆开写尽量做到每一步都能照做。如果你刚接触 Git 和 GitHub想拥有一个属于自己的网站主页这篇会是你今天就能跑通的一条路。整个流程的核心就三件事把仓库命名正确把页面文件推到远端分支把 GitHub Pages 开关打开。难度不高但我见过很多人卡在“仓库名不对”“改了代码却看不见变化”“页面 404”这些点上。下面按实际搭建顺序走一遍把每个操作背后的原因也讲清楚。1. 先搞清楚 GitHub Pages 能做什么不能做什么1.1 它其实是把“仓库”变成“网站”GitHub Pages 的原理并不复杂你在 GitHub 上创建一个仓库仓库里放的是静态文件比如 index.html、样式表、图片、Markdown 文档。然后 GitHub 会自动把这些文件放到一个公开的网站地址上。默认地址格式是https://你的用户名.github.io这个地址就是你的个人网站入口。之后你只要往仓库里推送新的文件网站内容就会跟着更新。整个过程相当于把“代码托管”和“静态网站托管”合并到了一起不需要你自己启动服务也没有服务器进程要维护。这对个人主页场景非常合适。你想展示个人介绍、项目经验、技术博客、简历、作品集都可以用这套方式。GitHub 免费账号可以把公开仓库直接发布成网站成本基本为零。1.2 适合个人主页但不要当成应用服务器我在实际操作中会把 GitHub Pages 的能力边界画得很清楚它擅长托管静态内容不擅长跑后端逻辑。下面是常见的判断标准。用途是否适合原因个人简历 / 个人介绍页适合静态页面直接展示免费 HTTPS技术博客 / 项目文档适合支持 Jekyll也能配合静态站点生成器产品落地页 / 活动页适合流量不大时部署非常快用户登录 / 后台管理不适合没有服务端程序数据库更不可能文件上传 / 实时交互不适合只能放静态内容WebSocket 等场景没法直接用高并发接口不适合它不是为应用服务器设计的所以如果你想搭建的是一个“有技术含量”的个人网站主页GitHub Pages 完全够用如果你想搭建的是带用户系统的应用平台那应该换一台服务器或者使用云服务。这是第一件需要明确的事不要把 GitHub Pages 当成万能容器。1.3 免费不等于没有使用限制GitHub Pages 虽然免费但它要求仓库内容适合公开访问。如果你要做个人主页仓库本身是公开的内容也基本是公开的。这一点本身没问题但要注意不要把数据库连接字符串、API 密钥、私密配置传到仓库里。只要是公开仓库推送前就要想清楚什么能放、什么不能放。如果你非要私有仓库也不是完全不行但我的建议很直接个人主页这类内容使用公开仓库最稳妥。公开仓库不仅方便 GitHub Pages 生成网站也方便别人直接看你的代码还符合开源交流的默认习惯。2. 建站前准备账号、仓库名和本地工具2.1 注册 GitHub 账号想好你的用户名如果还没有 GitHub 账号先去官网注册。注册时最重要的一个选择是用户名因为你的个人网站地址和用户名强相关。默认网站地址是这样的https://你的用户名.github.io比如用户名是zhangsan网站地址就是https://zhangsan.github.io。用户名也会出现在你的项目地址里比如https://github.com/zhangsan/project-name。所以注册时尽量不要用一串无规律数字或者容易被误解的词。我一般建议用姓名拼音、英文名、或者固定的个人品牌 ID。这个用户名一旦被习惯性使用后面想改会很麻烦因为历史链接全要跟着变。注册完成后记得先去邮箱点验证链接。没有验证邮箱时很多操作会受限。2.2 本地需要安装的软件整个教程里本地机器真正必需的只有一个Git 客户端。文本编辑器选一个顺手的即可VS Code 是当前很常见的选择用记事本也能完成最基础的操作但不建议因为你需要能看清文件的目录结构和行尾格式。安装完 Git 后可以先确认版本git --version能输出版本号说明安装成功。如果系统提示找不到命令大概率是安装后没有重启终端或者没有把 Git 加到系统 PATH 里。2.3 关于网络环境要提前说的现实问题GitHub 是国外平台不同网络环境下访问速度确实有差异。有的网络下打开页面很快有的网络下会偶尔超时。这个现象不是代码问题也不是仓库问题通常和本地网络链路有关。我的建议是先确认 GitHub 官网本身能不能正常打开。打开慢的时候不要反复点击耐心等待一段时间再刷新。如果某个操作一直失败可以换个浏览器、换个网络环境再试。更准确的运行状态可以看 GitHub 官方状态页以官方页面显示为准。我不会在这篇教程里介绍任何访问工具或镜像手段。原因很简单这属于网络环境问题不能用额外工具去绕也不该作为建站教程的核心。你的目标是把 GitHub Pages 用起来重点关注仓库和部署逻辑就好。2.4 准备 SSH 还是使用 HTTPS克隆和推送仓库时常见有两种方式HTTPS 和 SSH。HTTPS 方式地址长这样https://github.com/用户名/仓库名.git。最直接不需要生成密钥但推送时通常需要用到 Personal Access Token而不是账号密码。SSH 方式地址长这样gitgithub.com:用户名/仓库名.git。需要先在本地生成 SSH Key再把公钥配置到 GitHub之后推送不需要重复输入密码。新手我建议先用 HTTPS 加 Personal Access Token 的方式。步骤少逻辑清晰。等你对 Git 操作熟悉了再考虑 SSH。Personal Access Token 的获取路径是GitHub 右上角头像 - Settings - Developer settings - Personal access tokens - Tokens (classic) - Generate new token。生成时勾选repo权限范围即可。需要注意这个 Token 只在生成页面显示一次之后不会再看得到必须自己保存好。3. 第一次创建个人网站最小可用版本3.1 创建仓库仓库名必须是“用户名.github.io”登录 GitHub 后点击右上角的加号选择 New repository。这时最关键的一步来了仓库名必须填写成“你的用户名.github.io”。这不是可选项而是 GitHub Pages 的命名规则。比如你的用户名是zhangsan仓库名就是zhangsan.github.io如果你的用户名是lisi仓库名就是lisi.github.io只有仓库名符合这个规则GitHub 才会自动把该仓库发布到对应域名。其他仓库名虽然也能开启 Pages但需要在设置里手动指定项目站点网址会带上仓库名后缀不够简洁。个人主页用“用户名 github.io”这种命名最稳。创建仓库时可以选择 Public。Description 里可以写一句“个人网站”之类的说明。建议大家顺手勾选“Add a README file”这样仓库里一开始就有一个 README.md方便后面验证 Pages 是否生效。创建完成后你会在仓库主页看到一个初始 README 文件。这一步只是准备阶段网站还没真正上线。3.2 开启 GitHub Pages 开关进入刚创建的仓库点击顶部导航的 Settings然后找到左侧菜单里的 Pages。在 Build and deployment 区域里把 Source 设置为Deploy from a branch分支选择main目录选择/ (root)然后点 Save。这里解释一下为什么要这样设置GitHub Pages 需要知道“从哪个分支的哪个目录发布网站”。默认 main 分支就是最常用的发布分支。把根目录作为发布目录意味着仓库根目录下的 index.html 会被当成网站首页。如果你以后想用 docs 文件夹作为网站目录也可以改成/docs但个人主页建议直接用根目录简单直接。保存后GitHub 会开始构建页面。首次构建一般需要一两分钟也可能更久一点。构建完成后Pages 设置页面会显示你的网站地址。3.3 访问地址判断是否成功打开浏览器访问https://你的用户名.github.io默认情况下因为仓库里没有 index.html网站可能会显示 README 的内容或者一个简单的目录列表。只要没有出现“404 Page not found”这种错误就说明 Pages 已经生效了。如果你看到 404不要急着怀疑代码先按这个顺序检查仓库名是不是“用户名.github.io”精确到大小写。用户名拼写是否正确网址里的用户名与账号用户名是否一致。Settings - Pages 里的 Source 是否已经保存成功。是否还在构建中。刚保存后等几分钟再刷新。这个最小版本的意义是先把“仓库 - 页面”这条路打通。路通了后面改内容才有意义。如果这一步就卡住往下走很容易把问题混在一起。第一次遇到 404最可能是名字拼写错误或 Pages 还在构建。先排除这两点再考虑代码问题。4. 把默认页面改造成自己的主页4.1 克隆仓库到本地网站通路确认之后就可以开始改内容了。先把远端仓库克隆到本地。在本地目录执行git clone https://github.com/你的用户名/你的用户名.github.io.git注意替换成你自己的用户名。执行完成后会多出一个文件夹名字就是仓库名。进入目录cd 你的用户名.github.io如果你的仓库里已经有 README.md这个文件就在本地目录里。4.2 认识静态网站的入口文件对于静态网站浏览器访问一个网址时默认会寻找该目录下的index.html。所以最直接的页面控制方式就是新建一个index.html。先创建一个最简单的 HTML 文件!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的个人主页/title /head body h1你好我是网站作者/h1 p这个页面由 GitHub Pages 托管。/p /body /html保存为index.html放在仓库根目录。先把这段最简单的内容跑通。后面的美化、主题、博客功能都可以在这个基础上一层层加。很多人喜欢一上来就找复杂主题结果一堆样式报错。更合适的做法是先确认“我的 html 会被正确展示”再考虑提升视觉效果。4.3 提交并推送修改本地文件改好之后需要推送到 GitHub 仓库。第一步查看当前仓库状态git status会看到index.html处于未跟踪状态。接下来把文件加入暂存区git add index.html也可以使用git add .把当前目录所有改动加入暂存区。个人项目里用git add .比较方便但要养成习惯提交前先看git status确认没有误加文件。然后提交git commit -m 添加个人主页首页最后推送git push如果这是第一次使用 HTTPS 方式推送Git 会要求输入用户名和 Token。用户名就是你的 GitHub 用户名密码处输入 Personal Access Token而不是账号密码。4.4 判断修改是否生效推送成功后回到浏览器刷新https://你的用户名.github.io。如果看到了“你好我是网站作者”说明整个链路已经完整跑通。如果没看到变化按这个顺序排查是否真的推送成功看命令行有没有main分支的 push 输出。是否已经访问到正确网址网址是不是少了www或者多了其他字符。浏览器是否有缓存可以按Ctrl F5强制刷新。GitHub Pages 是否还在构建推送成功后到页面更新可能还需要一分钟。我第一次跑的时候经常卡在“已经 push 成功但页面没变”这一步。后来发现多半是浏览器缓存或者构建延迟。遇到这种情况先不要反复改代码等几分钟再说。5. 让个人主页更有技术含量从单页到博客与文档站5.1 如果只是单页可以不用 JekyllGitHub Pages 原生支持 Jekyll但这不是强制使用的。你完全可以只放静态 HTML 文件GitHub 会原样展示。单页主页、作品集页面用纯 HTML 就够了。但如果你想写技术博客让文章按日期排列、自动生成列表那 Jekyll 就派上用场了。Jekyll 会在 GitHub 构建阶段把 Markdown 文件转换成 HTML 页面。你可以新建一个_config.yml内容类似title: 我的技术博客 description: 记录技术与生活 theme: minima然后在仓库根目录新建_posts文件夹文件名格式要求是YYYY-MM-DD-文章标题.md例如2025-08-01-first-post.md文件名里的日期会作为文章发布日期。文章内部可以写 Markdown 正文--- layout: post title: 我的第一篇文章 --- 这里写正文内容。推送后Jekyll 会自动处理这些 Markdown 文件生成一个简单博客。这里要提醒一点如果仓库里已经有一个自己的index.html且用了非 Jekyll 的静态页面Jekyll 的解析可能会受index.html影响。如果你决定用 Jekyll 做博客最好先了解它默认的目录结构和首页生成方式不要把两套逻辑混在一起。更简单的判断标准是只想放一个主页就用纯 HTML想写多篇文章再考虑 Jekyll 或静态站点生成器。5.2 不同建站方式的取舍个人主页发展到一定阶段会有人开始纠结是继续用纯 HTML还是上 Hexo、Hugo、VuePress我的建议很明确每个工具都有自己的适用场景不要因为别人都在用就盲目引入。方式适合场景学习成本构建复杂度纯 HTML单页介绍、作品集低最低JekyllGitHub Pages 原生支持适合轻量博客中低Hugo内容多、想本地构建快中高中Hexo前端生态熟悉喜欢 Node.js 工具链中高中VuePress写文档站中高中核心原则是先用最小方案跑通再考虑扩展。我对很多人的建议是第一版个人主页用纯 HTML 加少量 CSS第二次迭代再引入 Jekyll。这样每次只有一个新的变量出问题也容易定位。5.3 用静态站点生成器时的部署差异如果使用 Hugo 或 Hexo本地通常会先执行构建命令生成一个public或类似名称的静态目录然后把这个目录里的内容推送到 GitHub Pages 仓库。Hugo 的常见步骤是hugo new site mysite cd mysite hugo new posts/first-post.md hugo最后一条命令会生成静态文件。之后把这些文件放到仓库对应目录里或者配置 GitHub Actions 自动构建。Hexo 的常见流程类似npm install -g hexo-cli hexo init blog cd blog npm install hexo g生成的静态文件默认在public目录。这里不需要背命令重点是理解流程静态站点生成器负责把 Markdown 和主题合并成 HTMLGitHub Pages 只要负责托管这些 HTML。至于在本地构建还是在 GitHub Actions 里构建是可以选择的事。5.4 添加 404 页面和项目说明做网站主页时404 页面很容易被忽略。但访问者只要输错地址就会看到 GitHub 默认的 404 页面。你可以在仓库根目录添加404.html内容可以简单写!DOCTYPE html html langzh-CN head meta charsetUTF-8 title页面不存在/title /head body h1404/h1 p这个页面不存在返回 a href/首页/a。/p /body /html推送到仓库后GitHub Pages 会自动展示这个页面。另外仓库里的README.md很重要。虽然它不一定直接展示在个人网站页面上但在 GitHub 仓库首页会展示别人打开你的仓库时首先看到的就是它。README 里可以写清楚这个网站是什么、包含哪些内容、如何部署。这也是“个人主页”含金量的一部分。6. 绑定自定义域名可选但推荐6.1 为什么我的建议是绑定自己的域名默认的https://你的用户名.github.io已经完全能用了但它不够像一个真正的个人品牌主页。绑定自定义域名后网站会稳定很多也更容易让别人记住。自定义域名需要自己去域名服务商处购买。这一步不是必须的如果你只是想先体验 GitHub Pages完全可以跳过。等确认网站会长期维护再买域名。6.2 在仓库里添加 CNAME 文件绑定域名之前先在仓库根目录新建一个CNAME文件文件内容就是你的自定义域名注意不要加http://也不要加路径。比如www.example.com把example.com替换成你自己购买的域名。推送这个文件到仓库后再去 GitHub 仓库的 Settings - Pages 里找到 Custom domain 输入框填上同样的域名点击 Save。这里要说明CNAME 文件和 Pages 设置里填写的域名需要保持一致。两者不一致时会导致绑定不稳定。6.3 DNS 解析配置域名绑定到 GitHub Pages 后还需要去域名服务商的控制台配置 DNS 解析。常用做法是添加一条 CNAME 记录主机记录www 记录类型CNAME 记录值你的用户名.github.io意思是把www.example.com指向你的用户名.github.io。如果你想让裸域名也能访问不同服务商的配置方式不同。最稳妥的做法是看域名服务商提供的 DNS 配置帮助页按它的规则配置。不要随便填 A 记录指向固定 IP因为 GitHub Pages 的 IP 不是长期不变的用 CNAME 更安全。DNS 配置完成后生效时间可能很快也可能需要几个小时。如果绑定后访问不到先别急等一段时间再刷新。6.4 开启 HTTPS域名解析生效后回到 Settings - Pages这时页面底部一般会出现 Enforce HTTPS 的选项。勾选它GitHub 会为你的自定义域名申请 HTTPS 证书。需要注意HTTPS 证书的签发需要时间第一次开启后可能要等一段时间。如果勾选项是灰色不可用通常表示证书还没就绪等一段时间再刷新。这个步骤完成之后你的个人网站地址就从https://你的用户名.github.io变成了https://www.example.com。7. 日常更新、自动部署与常见问题排查7.1 推送即部署GitHub Pages 的更新逻辑可以概括成一句话推送到指定分支GitHub 自动重新构建并发布。你不需要登录服务器也不需要重启任何服务。所以日常更新个人主页的流程是本地修改文件。用git add添加改动。用git commit提交改动。用git push推送到 GitHub。等一两分钟刷新网站。这套流程和日常写代码完全一致。你既是开发者也是站点管理员。7.2 用 GitHub Actions 做更复杂的构建如果你使用了 Hugo、Hexo、VuePress 这类静态站点生成器除了在本地构建后推送静态文件也可以配置 GitHub Actions让 GitHub 在云端自动构建。大体逻辑是你推送的是源码和生成配置GitHub Actions 根据工作流文件安装依赖、执行构建命令然后把生成结果发布到 Pages。在仓库里创建目录.github/workflows/然后放一个工作流文件。下面是一个很常见的通用结构示例不是每条命令都必须照抄要根据具体生成器调整name: Build and Deploy on: push: branches: - main jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Build Env run: echo 这里根据具体生成器安装依赖 - name: Build run: echo 这里执行构建命令 - name: Deploy run: echo 这里上传生成的静态目录使用 GitHub Actions 时我建议你先在本地把构建命令跑通再写工作流。否则报错时很难区分是源码问题、环境问题还是 Actions 配置问题。不过话说回来如果你只是需要一个个人主页Jekyll 和纯 HTML 已经足够Actions 不是必须的。它属于进阶玩法。7.3 高频问题排查顺序下面这些是我整理个人主页时最常见的排查点直接列成表方便对照。现象优先排查顺序判断标准页面 404仓库名 - 分支名 - Pages 设置 - 构建是否完成仓库名必须精确等于“用户名.github.io”修改后页面没变是否 push 成功 - 是否被浏览器缓存 - 是否还在构建push 输出没有错误等待后强制刷新样式全部错乱页面里的 CSS 路径是绝对路径还是相对路径 - 资源文件是否被提交路径少了一级目录是常见原因推送时提示认证失败是否使用 HTTPS - 是否用 Token 而不是密码 - Token 权限是否包含 repo输入账号密码通常无效自定义域名不生效CNAME 文件是否存在 - 域名拼写是否一致 - DNS 解析是否正确 - 等待时间域名记录生效需要时间图片显示不出来图片仓库路径 - 文件名大小写 - 是否推送GitHub 文件路径区分大小写遇到报错时不要先怀疑 GitHub Pages 本身有问题先看最近改动的是什么。这是我排查时的习惯性动作先看git status和git log确认本地上一次提交了什么再对照线上效果。很多时候问题出在“本地文件已经改了但没有提交”或者“提交了但没推送”。7.4 维护建议日志、备份、敏感信息个人网站虽然简单但维护节奏还是要有的。建议保留一个README.md写上“这个网站是怎么部署的、如何本地预览、如何发布新文章”。这样即使隔了几个月再回来维护也能快速回忆起来。建议每次修改用清晰的commit message不要只写“update”。提交信息写清楚比如“新增项目经历页面”“修复移动端样式问题”“添加关于页面”后续查找历史版本时会方便很多。最需要注意的是敏感信息。因为 GitHub Pages 对应仓库通常是公开的任何推送到仓库的文件都可能被其他人看到。.env文件、密码、Token、私钥等一概不能放进仓库。我见过有人把 Personal Access Token 写进文件里然后误推上去结果还要大费周章改密钥。这个问题只要提交前多看一眼git status基本就能避免。最后说点实际体验个人网站主页不是一个越复杂越好的项目。用 GitHub Pages 建站的真正价值是让你能用版本控制的方式来管理自己的网页内容同时不需要关心服务器、数据库、运维这些额外负担。对于个人介绍、技术博客、作品展示这套组合已经非常够用。我建议你把第一次尝试控制在最小范围一个正确命名的仓库一个开启的 Pages 开关一个简单的 index.html。跑通之后再添加主题、自定义域名、自动构建。先把基础链路走稳再把体验一步步做厚这才是这个方案最省心的用法。