把个人网站主页部署到 GitHub 上用 GitHub Pages 对外发布是开发者搭建个人主页最常用的方式之一。只要你有一个 GitHub 账号就可以拥有一个形式完整、具备 HTTPS 访问能力、还能绑定自己域名的静态站点整个过程不需要购买云服务器也不需要维护 Nginx 或容器环境。这篇文章会从“为什么要用 GitHub Pages”讲起然后走一条完整路线创建仓库、写首页、提交代码、开启 Pages、用 GitHub Actions 自动部署、再切换到 Jekyll 管理内容最后绑定自定义域名并处理常见的部署问题。无论你是刚入门的技术爱好者还是已经写过项目但没系统整理过个人主页的开发者这套流程都可以直接照做。整个方案可以拆成两条路线快速路线本地写一个index.html推到 GitHub在仓库设置里开启 Pages几分钟后就能访问。进阶路线使用 Jekyll 模板管理内容和主题通过 GitHub Actions 自动构建绑定自己的域名并启用 HTTPS。两条路线共用同一个底层机制所以先搞清楚 GitHub Pages 是什么后面的每一步都会顺畅很多。1. 先搞清楚 GitHub Pages 的定位和边界1.1 GitHub Pages 免费帮你做好的三件事GitHub Pages 是 GitHub 提供的静态站点托管服务。它不是一个完整的云主机它只负责“接收静态文件、生成页面、对外托管”但它把三件很麻烦的事都替你处理了第一静态文件的全球分发。你不需要自己配置 CDNGitHub Pages 会通过自己的基础设施分发页面访问速度整体比较稳定。第二HTTPS 证书。只要是 GitHub 提供的默认域名username.github.io证书会自动生效。绑定自定义域名后只要 DNS 配置正确证书也可以自动签发和续期。第三和 Git 工作流天然集成。你每次git push都会触发新的发布历史版本可以回滚页面内容就是仓库里的代码和文件管理体验和管项目源码完全一致。1.2 什么内容适合放在 GitHub Pages 上个人网站主页、简历页、作品集、项目介绍页、个人博客、开源项目文档站这些都属于典型的静态站点非常适合放在 GitHub Pages 上。但不适合把需要后端服务的功能放在这里比如用户登录、订单处理、数据库写入、动态接口。如果主页里要显示实时数据正确做法是把 GitHub Pages 当作前端展示层让页面通过 API 请求你自己的后端服务。还需要注意GitHub Pages 对单站大小和流量有使用限制常见说明是发布内容不能超过 1GB带宽也有软性限制。个人主页远达不到这个规模但如果想用来托管大量高清图片或视频文件就不合适了。1.3 仓库、分支和 Pages 发布来源的关系一个 GitHub Pages 站点通常由一个仓库驱动。对你最关键的是仓库名用户主页仓库名必须是username.github.io其中username是你的 GitHub 用户名。项目主页仓库名可以是任意名字发布后访问路径会变成username.github.io/repo-name/。发布来源有两种常见选择。一种是在仓库的 Settings - Pages 页面里选择“Deploy from a branch”然后指定main分支和目录根目录或docs目录。另一种是选择“GitHub Actions”通过工作流文件控制构建和发布。对于个人主页最省心的是把仓库命名为username.github.io因为语义清晰、访问路径干净而且后续绑定自定义域名时不需要处理子路径问题。2. 环境准备与仓库初始化2.1 本地工具清单和检查命令在写页面之前先把本地环境确认一遍。最基础的工具是 Git 和一个代码编辑器。工具用途检查命令Git提交和推送代码git --version代码编辑器编辑 HTML、CSS、Markdown任意编辑器均可Ruby可选本地运行 Jekyllruby -vBundler可选管理 Jekyll 依赖bundle -v如果只写纯 HTML不需要安装 Ruby。如果要使用 Jekyll再安装 Ruby 环境。安装完成后先配置 Git 的用户信息否则提交时会出现“作者信息缺失”的提示。git config --global user.name your-name git config --global user.email youexample.comuser.name会显示在提交记录里user.email建议和 GitHub 账号绑定的邮箱保持一致这样你的提交记录能正确关联到 GitHub 主页。2.2 创建 GitHub 仓库并选择可见性登录 GitHub 后点击右上角的选择New repository。仓库名如果是个人主页就填写username.github.io这里的username必须和你的 GitHub 用户名完全一致大小写也要准确。可见性怎么选个人主页内容通常没有保密需求选择 Public 是最方便的。Public 仓库可以让 GitHub Pages 的构建和部署流程更顺畅也方便别人看到你的主页源码这对个人展示是有加分的。如果因为某些原因把仓库设成了 Private需要先确认当前 GitHub 套餐是否支持从私有仓库发布 Pages。不同时期、不同套餐的规则会有变化不要想当然。创建仓库时可以勾选Add a README file也可以不勾选。为了保证后续操作干净建议不勾选任何初始化文件直接创建一个空仓库然后从本地推代码。2.3 本地初始化和第一次提交在本地建一个和仓库同名的目录进入目录后初始化 Gitmkdir username.github.io cd username.github.io git init git branch -M main添加远程仓库地址。如果使用 HTTPS 方式git remote add origin https://github.com/username/username.github.io.git如果使用 SSH 方式git remote add origin gitgithub.com:username/username.github.io.git两种方式都可以使用 SSH 需要先配置好 SSH Key。第一次提交时先创建一个index.html文件再进行提交git add . git commit -m init homepage git push -u origin main推送成功后仓库里能看到完整的文件列表这就是后面所有自动化操作的基础。3. 用纯 HTML 搭建第一个可运行主页3.1 页面骨架文件 index.htmlGitHub Pages 在访问根路径时会优先找index.html。所以第一个文件必须是这个名字内容不需要复杂但结构要完整。下面是一个适合个人主页的最小页面骨架!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 title我的个人主页/title link relstylesheet hrefstyle.css /head body header h1你好我是 [你的名字]/h1 p前端 / 后端 / 运维 / 兴趣方向/p /header main section h2关于我/h2 p写一段自我介绍突出你会什么、正在做什么、想找什么样的人合作。/p /section section h2项目/h2 ul lia hrefhttps://github.com/username/project-a项目 A 仓库/a/li lia hrefhttps://github.com/username/project-b项目 B 仓库/a/li /ul /section /main footer pa hrefmailto:youexample.com联系我/a/p /footer /body /html这个页面包含了个人主页最核心的几个区块头部标语、个人介绍、项目链接、联系方式。meta nameviewport一定要保留否则手机上访问时页面宽度会异常。3.2 添加样式并适配手机端纯 HTML 页面文字出来后还需要一个style.css让页面不至于太简陋。下面的样式尽量保持简单但已经处理好布局和移动端适配:root { --main-color: #2563eb; } * { box-sizing: border-box; } body { font-family: system-ui, -apple-system, PingFang SC, Microsoft YaHei, sans-serif; margin: 0; line-height: 1.7; color: #1f2933; } header { background: var(--main-color); color: #fff; padding: 4rem 1rem; text-align: center; } main { max-width: 760px; margin: 0 auto; padding: 2rem 1rem; } section { margin-bottom: 2.5rem; } a { color: var(--main-color); } footer { text-align: center; padding: 2rem 1rem; color: #52606d; } media (max-width: 600px) { header { padding: 2rem 1rem; } main { padding: 1rem; } }这里使用了 CSS 变量--main-color后续想换主题色时只需改这一处。max-width加margin: 0 auto是让内容在大屏上保持舒适的阅读宽度避免文字撑满整行。3.3 用 README 和 404 页面补齐站点体验个人主页虽然只有几个页面但建议补上两个文件。第一个是README.md它不会出现在你的主页页面里但会展示在仓库文件列表下方。可以写清楚这个仓库的结构、如何本地预览、如何部署方便别人看代码时快速理解。第二个是404.html。当访问者输入了错误地址GitHub Pages 会返回默认 404 页面但默认页面里没有回到你主页的入口。自定义一个更友好!DOCTYPE html html langzh-CN head meta charsetUTF-8 title页面不存在/title /head body styletext-align:center;padding-top:80px;font-family:system-ui,sans-serif; h1404/h1 p你访问的页面不存在回到 a href/首页/a。/p /body /html这里的/在用户主页username.github.io下没有问题。如果站点部署在项目路径下比如username.github.io/repo/需要把链接改成相对路径或加上baseurl否则会跳错位置。3.4 在仓库设置中开启 GitHub Pages推到远程仓库后打开仓库页面进入 Settings - Pages在Build and deployment区域选择Deploy from a branch分支选择main目录选择/root点击 Save。保存后 GitHub 会开始构建。等待一两分钟访问https://username.github.io如果能看到刚才写的 HTML 内容就说明第一个简单版本的个人主页已经上线了。这个流程不需要额外安装任何依赖适合快速验证。如果想做得更有工程感就需要进入下一步用 GitHub Actions 控制构建过程。4. 用 GitHub Actions 把构建部署变成自动化流程4.1 为什么建议用 Actions 而不是只开默认 Pages直接选Deploy from a branch对纯 HTML 很省事但有一个局限你无法在发布前执行构建步骤。比如你用了 Jekyll、Hugo、React 静态导出或者需要在发布前压缩图片、生成站点地图GitHub 分支发布模式就满足不了了。GitHub Actions 可以解决这个问题。它会在你git push后自动执行工作流把构建产物上传到 Pages 并发布。这样部署流程完全由代码定义和项目一起版本化换电脑后不需要重新配置。对于纯 HTML 项目Actions 的价值更多在于“统一发布入口”。对于 Jekyll 或静态站点生成器项目Actions 则是必须的因为发布的是构建后的文件不是源码本身。4.2 Workflow 文件怎么配置在仓库根目录创建.github/workflows/deploy.yml写入下面的内容。这个工作流针对静态 HTML 项目name: Deploy static content to Pages on: push: branches: - main workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Pages uses: actions/configure-pagesv5 - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: . - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4逐段解释一下on.push.branches只在main分支收到推送时触发。workflow_dispatch允许你在 Actions 页面手动点击Run workflow用于重新发布。permissions声明工作流需要的权限。pages: write用于发布id-token: write用于 GitHub Pages 部署时的身份验证。concurrency防止多个部署任务同时运行避免发布状态冲突。actions/upload-pages-artifact把根目录内容打包为部署产物。actions/deploy-pages真正把产物发布到 Pages。保存 Workflow 后回到仓库的 Actions 标签页能看到这个工作流正在运行。等它跑完去仓库 Settings - Pages 页面会发现发布来源已经变成GitHub Actions。如果使用 Jekyll工作流需要在Upload artifact之前增加构建步骤核心命令是bundle exec jekyll build --baseurl ${{ steps.pages.outputs.base_path }}这里--baseurl很关键项目部署在子路径时缺少它会找不到样式和链接。4.3 触发构建后从哪里看结果每次推送代码进入 Actions 页面点开最新一次运行记录可以看到每个 Step 的状态。绿色对勾表示成功红色表示失败。失败时需要重点看两个地方失败的 Step 日志中是否有报错关键字比如error、Command failed、Cannot find module。日志中打印的文件路径是否和仓库实际目录一致。GitHub Actions 的日志是排错的第一入口不要只看最终结果。日志里会显示执行环境、依赖安装结果、构建命令输出这些信息比“部署失败”四个字有用得多。5. 进阶用 Jekyll 管理内容和主题5.1 Jekyll 的核心工作方式Jekyll 是一个静态站点生成器它把 Markdown 和模板文件组合成静态 HTML。你不需要每次手动改 HTML 里的重复导航、页脚、文章列表写完 Markdown 后运行构建命令Jekyll 会自动生成完整页面。理解 Jekyll 只需要抓住三个概念_config.yml站点全局配置。Front MatterMarkdown 文件头部用---包裹的元数据。Layout页面模板多个内容页共用同一个布局。这种工作方式非常适合个人主页和博客因为内容维护成本很低。你只需要专注写 Markdown页面结构和样式交给模板管理。5.2 目录结构和 Front Matter一个典型的 Jekyll 个人主页结构如下. ├── .github/ │ └── workflows/ │ └── deploy.yml ├── _config.yml ├── _posts/ │ └── 2026-01-01-welcome.md ├── assets/ │ └── style.css ├── about.md ├── index.md └── 404.md_config.yml是最重要的配置文件title: 我的个人主页 description: 这里有我的项目记录和技术思考 baseurl: url: https://username.github.io theme: minima如果仓库名是username.github.iobaseurl一般保持空字符串。如果部署在/repo/路径下baseurl要写成/repo这个值必须和访问路径保持一致。Markdown 文件头部可以写 Front Matter。以index.md为例--- layout: home title: 首页 --- # 你好我是 [你的名字] 这里可以写一段简短的介绍。layout的值取决于你使用的主题。minima主题提供home、page、post等布局具体名称以主题文档为准。文章文件必须放在_posts目录命名格式是YYYY-MM-DD-标题.md--- layout: post title: 2026 年的第一个更新 date: 2026-01-01 --- 这是文章的正文内容。Jekyll 会根据文件名中的日期自动归类所以不要随意改这个命名规则。5.3 本地预览 Jekyll 站点先在本地安装 Ruby 环境然后安装 Jekyll 和 Bundlergem install jekyll bundler如果你是从零创建 Jekyll 项目jekyll new my-site cd my-site bundle install启动本地开发服务器bundle exec jekyll serve打开http://127.0.0.1:4000就能实时预览页面。修改 Markdown 或配置文件后刷新浏览器即可看到效果。确认无误后提交源码并推送Actions 会负责在云端完成构建和部署。本地预览最大的价值是减少线上试错。你可以在本地先发现链接失效、样式错乱、文章列表异常而不是推送到 GitHub 后再看构建日志。6. 自定义域名和 HTTPS 证书6.1 域名解析记录怎么设置默认的username.github.io地址已经可以访问但它不够个性化。绑定自己的域名后主页入口更专业也方便记忆。到你的域名服务商后台添加两条解析记录。GitHub Pages 官方文档提供的常见配置如下主机记录记录类型记录值A185.199.108.153A185.199.109.153A185.199.110.153A185.199.111.153wwwCNAMEusername.github.io.A 记录用于根域名比如example.com。CNAME 记录用于www.example.com让它指向你的 GitHub Pages 默认域名。不同域名服务商对“根域名”的表达不同有的叫有的叫“空名称”。配置后需要等待 DNS 生效TTL 越短生效越快。6.2 在仓库中绑定自定义域名打开仓库 Settings - Pages在Custom domain一栏输入你的域名比如example.com点击 Save。保存后GitHub 会在你的仓库里自动创建或更新一个CNAME文件文件内容就是你的自定义域名。你不需要手动维护这个文件但要注意不要手动删除它。在 Pages 设置页面绑定后会在同一个位置看到Enforce HTTPS选项。建议立刻勾选开启这样访问者会强制使用 HTTPS 连接证书由 GitHub 自动签发。如果需要使用www.example.com作为主访问地址就在 CNAME 文件里填写www.example.com如果使用根域名就填写example.com。GitHub 通常会做跳转但主域名只能选一个。6.3 HTTPS 自动签发后的验证正确配置 DNS 后在终端执行curl -I https://username.github.io会返回类似HTTP/2 200的结果。绑定自定义域名后再执行curl -I https://example.com如果返回301跳转说明域名还没有完全生效或需要等待证书签发。HTTPS 证书不是立刻生成的DNS 记录生效后通常还要等待几分钟到几个小时。在浏览器里访问你的域名点击地址栏左侧的小锁图标查看证书是否有效。如果证书提示不安全优先检查 DNS 记录是否填错以及 CNAME 文件里是否有多余空格或重复域名。7. 发布后的验证、常见问题和排查路径7.1 页面发布成功不等于内容正确很多人在看到页面能打开后就认为部署完成了。但“能打开”和“内容正确”是两回事。完整验证应该覆盖这几个维度首页是否显示最新内容。图片和 CSS 是否能正常加载浏览器控制台有没有 404 或 MIME type 报错。自定义域名是否生效HTTP 是否跳转到 HTTPS。手机端布局是否正常导航、按钮、链接是否可点击。404 页面是否能正常显示并且能返回首页。仓库 Actions 的最新一次运行是否为成功状态。建议在无痕窗口里访问避免浏览器缓存干扰判断。完成一次发布后用无痕窗口强制刷新看到的才是真实线上效果。7.2 Actions 日志和仓库设置是排查入口遇到部署问题时不要凭感觉改代码。先确定问题发生在哪一层。第一层是仓库本身。检查index.html是否在指定目录文件名是否准确分支名是否和 Pages 设置一致。第二层是构建流程。进入 Actions 标签页查看最新一次运行日志。如果构建 Step 失败日志中通常有明确的错误信息。第三层是域名和证书。如果页面能通过username.github.io访问但自定义域名打不开问题大概率在 DNS 解析或 CNAME 文件而不是代码。第四层是浏览器缓存。如果代码和 Actions 都正常但看到的是旧页面先刷新再用无痕窗口验证。7.3 常见问题速查表问题现象可能原因检查方式处理建议页面一直显示旧内容浏览器或 CDN 缓存无痕窗口访问查看 Actions 运行时间等待几分钟后强制刷新确认最新提交已触发部署访问返回 404仓库名不对或没有index.html检查username.github.io仓库名检查发布目录重命名仓库或在发布目录放一个index.html自定义域名不生效DNS 记录类型或地址错误使用dig或Resolve-DnsName查询解析记录对照 GitHub Pages 官方文档修改 A/CNAME 记录等待 TTL 生效HTTPS 证书一直未签发DNS 未完成或 CNAME 文件有问题在 Pages 设置查看证书状态检查 CNAME 文件等待 DNS 生效确保 CNAME 文件只有一行域名Actions 构建失败YAML 语法错误或依赖版本不一致进入 Actions 日志查看失败 Step修正 Workflow 文件确认 Ruby、Bundler、Node 版本配置样式加载不出来CSS 路径错误或 baseurl 错误打开浏览器控制台看资源加载结果调整link路径或在 Jekyll 中使用relative_url使用 Jekyll 但页面没有任何样式baseurl和实际部署路径不一致检查_config.yml和页面源码里的链接项目部署在子路径时给样式和链接加上 baseurl这套排查顺序的核心是先确认输入再看路径再查依赖版本最后看网络和缓存。如果一开始就怀疑域名或 CDN反而容易绕路。8. 个人主页的内容组织和长期维护建议8.1 页面结构怎么设计个人主页不需要把所有内容都堆在首页。对于开发者来说首页最值得保留的是“你是谁、你在做什么、怎么联系你”这三件事。推荐的导航结构首页一句话介绍和核心项目入口。关于详细经历、技术栈、教育或工作背景。项目列出 2 到 4 个有代表性的项目每个项目说明解决的问题、技术方案和仓库链接。博客或笔记记录踩坑经历、学习笔记、项目复盘。首页不要写太长。真正能打动人的个人主页通常是打开后 3 秒内就能看懂你是做什么的。详细内容放在二级页面让读者自己选择点进去看。8.2 发布前检查清单每次更新完主页建议按下面清单检查一遍确认改动已经提交并推送到正确分支。确认index.html或 Jekyll 首页内容已更新。确认新增文图片使用相对路径避免子路径下失效。确认自定义域名解析和 HTTPS 证书状态正常。确认没有把密钥、.env文件、数据库连接串提交到仓库。确认 Actions 日志全部通过。确认无痕窗口访问后页面样式、链接、404 页面正常。这个清单可以在每次发布时固定使用。它不需要很复杂但能避免最常见的“推上去就忘等真出问题才发现”。8.3 学习环境、测试环境、生产环境的差异在本地运行bundle exec jekyll serve时很多问题不会暴露因为路径、环境变量和线上不一样。学习环境的目标是快速看到页面效果所以可以忽略性能、缓存、域名问题。测试环境一般就是你的username.github.io默认域名。这里可以验证部署流程、文章内容和样式是否符合预期但还没有正式绑定自定义域名。生产环境则是你绑定自定义域名、开启 HTTPS 后的正式站点。进入生产环境后还需要额外考虑页面访问速度和资源体积。图片是否经过压缩。是否配置了站点地图和 SEO 基础信息。是否开启了访问统计。是否有回滚方案比如保留上一个提交的 tag。对于个人主页不需要一开始就做到企业级复杂度。但至少要保持“每次提交都能构建、每次构建都可回滚”的底线这样长期更新时心里才有底。8.4 后续扩展方向GitHub Pages 虽然是静态托管但它可以承载的内容其实不少。后续可以逐步加入Jekyll 博客和文章分类。RSS 订阅地址。通过第三方评论服务实现文章评论区。使用 GitHub API 展示仓库和 stars 数量。增加暗色模式切换。为项目页面单独写 README 和部署说明。到这一步你已经不只是完成了一个个人网站主页而是掌握了一条完整的“源码管理 自动构建 静态托管 自定义域名”的发布链路。这条链路不只能用于个人主页也能迁移到项目文档站、团队介绍页、产品落地页等场景。个人主页最值得投入的不是一次性把页面做得多炫而是持续更新。每完成一个项目就在主页上补充一条记录每踩过一个坑就写一篇笔记。保持这个习惯比任何花哨的动画都比不上。