简介：一份依托代码托管平台静态页功能的轻量级站点源码包，面向网页前端和静态博客初学者，可帮助快速理解个人站点从内容组织到发布上线的最小实现，整体结构非常精简。压缩包共5个文件，包括2个Markdown文档、2个HTML页面和1个YAML配置文件，分别承担内容编写、页面入口与站点全局配置，整个包只有2KB。站点主题为「猫妖酱的乳首开发日记」，在个人主页中展示了如何组织日记内容、接入第三方搜索验证代码，并配置页面元信息；已有17319人浏览下载。通过分析这些源码，可快速了解个人静态站点的目录规范、页面之间的链接方式以及验证文件与内容文件的配合方法，适合作为搭建个人日记或记录类站点的参考起点。 直接说结论：把一个个人项目放到 GitHub Pages 上，并且绑定成github.io域名，是目前成本最低、可控性最高的建站方式之一。站点本身就是静态资源，不需要服务器、不需要数据库、不需要备案，只要仓库在，页面就在。我给自己折腾过好几个这样的站点，踩过的坑和摸出来的门道，下面一次说清楚。
1. github.io 到底是什么，以及它适合做什么
1.1 它能干什么
GitHub Pages 是 GitHub 提供的静态站点托管服务，每个账号可以拥有一个username.github.io形式的专属域名，这个仓库名必须是username.github.io，对应的是该账号的主站。除此之外，每个普通仓库还可以开启 Pages 功能，生成username.github.io/repo-name/这样的项目子路径页面。
这里说的“静态站点”，意思是你的网站内容在浏览器请求之前就已经是完整的 HTML、CSS、JavaScript 文件了，不需要后端程序动态生成。好处非常直接：访问速度快、安全性高、几乎不用维护。
对我来说，最实用的几个用途包括：技术博客、个人作品集、项目文档、简历页面、工具聚合页。如果你只是想展示自己做了什么、写过什么、能做什么，github.io完全可以替代购买云主机 + 域名 + 配置环境的整套流程。
1.2 和“买服务器自建站”的区别
很多人第一反应是“我买台服务器，装个 Nginx，部署个 WordPress，不也能建站吗”，但这两者体验差异很大。
| 对比项 | GitHub Pages | 自购云服务器建站 |
|---|---|---|
| 费用 | 免费（公开仓库） | 需要购买服务器和域名 |
| 维护 | 无需操心 | 需要安装环境、打补丁、保证安全 |
| 访问速度 | 国内访问一般，可能需要 CDN 加速 | 可以选国内节点，速度更快 |
| 内容生成 | 纯静态文件 | 支持动态程序 |
| 学习成本 | 很低 | 较高 |
如果你需要的只是一个展示型或个人记录型网站，先别急着买服务器。GitHub Pages 完全够用，而且后期如果想迁移，静态文件去哪里都能部署，不存在绑定关系。
2. 从零开始搭建一个 github.io 页面
2.1 前置准备
你只需要三样东西：一个 GitHub 账号、一个代码编辑器（VS Code 足够）、一个本地 Git 环境。
如果还没有安装 Git，去官网下载对应系统的版本，安装后在终端执行下面两行，设置好你的身份信息：
git config --global user.name "你的用户名" git config --global user.email "你的邮箱"这是 Git 提交代码时用来标记作者身份的，不设置的话后面提交会报错或提示补全信息。
2.2 创建专属仓库
登录 GitHub 后，点击右上角加号，选择New repository。Repository name 那一栏，必须填写你的用户名.github.io。注意，这一步是强约束：只有完全匹配用户名，GitHub 才会把它识别为个人主页仓库。如果填错，后面即使部署成功，访问地址也对不上。
仓库权限保持默认的 Public，然后勾选Add a README file，最后点击创建。
这个仓库创建好之后，访问https://你的用户名.github.io，理论上你会看到 README 文件渲染出来的内容。不过有时候因为缓存或者初始化时间，可能需要等几分钟才能看到。
2.3 本地初始化项目
把仓库克隆到本地，开始写你自己的页面。
git clone https://github.com/你的用户名/你的用户名.github.io.git cd 你的用户名.github.io然后在项目根目录创建一个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>我的个人主页</title> <style> body { font-family: system-ui, sans-serif; max-width: 720px; margin: 80px auto; padding: 0 24px; line-height: 1.8; color: #333; } </style> </head> <body> <h1>你好，我是你的用户名</h1> <p>这里是个人网站的首页，记录我的项目与日常。</p> </body> </html>保存后，把这个文件提交并推送：
git add . git commit -m "初始化个人主页" git push origin main推送成功后，再访问你的github.io地址，就能看到自己写的页面了。
2.4 使用 Jekyll 快速搭建博客
如果你不想从零写 HTML，GitHub Pages 原生支持 Jekyll 静态站点生成器。它的逻辑是：你按照约定好的目录结构写 Markdown 文章，Jekyll 自动生成完整的 HTML 站。
最省事的方法不是本地安装 Jekyll，而是使用现成的主题仓库。在 GitHub 上搜索jekyll-theme，挑一个 star 数高的，点击Use this template，以模板为起点创建你自己的仓库，然后把仓库名改成你的用户名.github.io。之后只需要修改_config.yml里的站点名称、描述、个人链接等配置，把_posts目录下的示例文章删掉，换成你写的 Markdown 文件，站点内容就完全变成你自己的了。
这里要特别注意_posts目录里的文件命名格式，必须是年-月-日-标题.md这种格式，例如：
2025-06-15-我的第一篇博客.md文件名里的日期会被当作文章的发布日期，不按这个格式命名，Jekyll 不会识别成文章。
3. 核心配置与部署细节
3.1 仓库的 Settings 不是摆设
推送完代码之后，很多人会在仓库的 Settings -> Pages 里面看到一堆选项，第一步要确认Source选择的是Deploy from a branch，分支选择main，根目录选/ (root)，点击 Save 保存。
如果用的是 Jekyll 主题模板，代码推送到 main 分支之后，GitHub Actions 会自动触发构建流程。你可以到仓库的Actions选项卡里看构建日志。第一次构建可能需要一两分钟，耐心等待即可。
有一个比较隐蔽的点：如果你的仓库之前被改名过，或者从别的仓库 fork 过来，可能导致部署失败。遇到这种情况，最直接的排查方式是去 Actions 页面看具体报错，根据错误信息调整，而不是反复重新推送。
3.2 自定义来源文件与项目子页面
如果你不只是做个人主页，还想为一个具体的项目单独建文档页面，可以在目标项目的仓库 Settings -> Pages 中，把Source设置为某个分支或者某个目录。
这里有个实际使用上的选择建议：对于纯静态项目，直接把编译产物放到gh-pages分支，路径指向 root；对于和源码混在一起的项目，可以把产物放在docs目录下，Source 选择main分支的/docs路径。gh-pages分支是 GitHub Pages 的默认约定分支，很多自动部署工具都认它，选它更通用。
3.3 自定义域名与 HTTPS
github.io自带的域名已经可以访问，但如果你想用自己购买的域名，GitHub 也支持配置自定义域名。
操作流程是：先在购买域名的服务商后台，添加一条 CNAME 解析记录，把www或者@指向你的用户名.github.io；然后在仓库 Settings -> Pages 的Custom domain里填入你的域名，点 Save。GitHub 会自动为这个域名申请 HTTPS 证书，不过证书签发需要一些时间，未生效之前不要关闭Enforce HTTPS选项。
这里容易踩坑的地方是：国内某些域名服务商对@根域名做 CNAME 解析可能不支持，只支持 A 记录。这种情况下，你需要先去查询你的用户名.github.io映射到的 IP 地址，然后把根域名用 A 记录指向这些 IP。注意，GitHub 的 IP 地址是有可能变化的，官方会通过邮件通知变更，所以有条件的话优先使用支持 CNAME 的服务商。
4. 实际维护中的常见问题与排查方法
4.1 访问 github.io 出现样式错乱
这个问题几乎每个折腾过的人都遇过。样式错乱的原因，绝大多数是资源路径写错了。
GitHub Pages 的路径分为两种情况：个人主页username.github.io的根路径是/，而项目页面的根路径是/repo-name/。如果你的站点是项目页面，但是引用了/css/style.css这样的绝对路径，浏览器会去username.github.io/css/style.css找文件，结果自然是 404。
解决方案有两种：一是把资源路径全部改成相对路径，比如css/style.css或者./css/style.css；二是在 HTML 里使用<base>标签，配合一个在构建时动态生成的路径变量。我的经验是，相对路径最省心，复制到任何环境下都不会因为域名或路径变化而出问题。
4.2 文章更新了但页面不显示
如果你使用 Jekyll，文章文件、图片、样式都改完了，推送后页面却没有变化，先用下面几个思路排查：
- 检查文件名是否符合
YYYY-MM-DD-标题.md格式； - 检查文件中是否正确配置了
layout，常用博客主题要求文章头部有layout: post； - 看仓库 Actions 的构建日志，是不是 Markdown 语法错误导致构建中断；
- 浏览器强刷一次（Mac 下 Cmd+Shift+R，Windows 下 Ctrl+F5），排除本地缓存。
有时候不是构建失败，而是 GitHub 的 CDN 缓存还在旧版本，这种情况等几分钟通常会恢复。
4.3 关于 404 页面
GitHub Pages 很贴心地支持自定义 404 页面。在仓库根目录添加一个404.html，访问不存在的地址时，就会自动展示这个页面。我建议每个站点都配上一个，既能提升体验，也显得专业。
一个最普通的 404 页面可以这样写：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>页面不存在</title> </head> <body> <h1>404</h1> <p>找不到这个页面，可能是地址写错了。</p> <p><a href="/">回到首页</a></p> </body> </html>4.4 国内访问速度优化思路
GitHub Pages 域名在国内的访问稳定性说实话一般，时快时慢，高峰期偶尔还会加载不出来。这个问题的根源在于 GitHub 的服务器不在国内，中间网络链路不可控。
在不动服务器的情况下，有几种优化手段可以使用：如果只是个人使用，可以考虑在浏览器端使用DevTools禁用缓存，频繁刷新页面帮助判断是否是网络问题；如果站点以图片等静态资源为主，可以把资源放到国内访问更快的对象存储服务（比如阿里云 OSS），然后在页面里引用这些外链资源。不过需要注意：GitHub Pages 本身不支持设置响应头，也没法通过代码控制 CDN 缓存策略，所以图片塞在仓库里并不是一个非常理想的做法。
另外，有一个不算技巧的技巧：尽量压缩图片和静态资源体积，减少请求数量，这能让页面加载快不少。图片压缩工具网上有很多，在线就行，不必装软件。
5. 把 github.io 玩出更多花样
5.1 用它做个人项目文档站
实际使用中，github.io除了做博客，非常适合拿来搭项目文档。很多开源项目都把用户手册放在 GitHub Pages 上，因为文档和代码保存在同一个仓库中，更新文档时直接改代码仓库里的 Markdown 文件，提交之后文档站就自动更新了，流程非常顺滑。
我个人的做法是把文档站的部署和主项目分开管理：主代码仓库里只放源码和docs目录，Pages 指向 docs；同时在新版本 release 发布时，自动触发一个构建流程，把生成的静态文档推到gh-pages分支。这样源码、文档、发布物三者都不互相干扰，维护起来很清爽。
5.2 利用 GitHub Actions 实现自动更新
如果你不想每次手动构建、推送，可以写一个简单的 GitHub Actions 工作流。工作流文件放在.github/workflows/main.yml，核心逻辑是：每当 main 分支有新的代码推送时，自动安装依赖、构建项目、把产物部署到 Pages 分支。
因为我前端项目比较常用的构建工具是 Vite，一个精简版的部署工作流大概长这样：
name: Deploy to GitHub Pages on: push: branches: [main] permissions: contents: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Node uses: actions/setup-node@v4 with: node-version: 20 - name: Install and Build run: | npm install npm run build - name: Deploy uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist这个配置文件写好后，后续只要推代码，站点就会自动重新部署，全程不用登录服务器、不用手动执行构建命令，体验非常舒服。
5.3 结合自己的需求做内容规划
回到一开始说的场景：一个个人站点，想清楚“放什么”比“怎么搭”更重要。我的建议是，把站点规划成三个核心板块：作品展示区、日志记录区、资源聚合区。作品展示区放你做过的项目或案例，配上链接和图片；日志记录区写踩坑经验、学习记录；资源聚合区放工具、书单、推荐链接。
内容不需要一开始就填满，先把框架搭出来，后续慢慢补充。对一个长期维护的个人站点来说，持续输出比一次性写完更重要。
6. 踩坑实录与经验补充
6.1 文件名大小写问题
GitHub Pages 是部署在 Linux 环境上的，文件系统区分大小写。如果你在本地 Windows 或 Mac 上开发时，引用了Image.jpg，但文件实际名称是image.jpg，本地预览可能正常，部署到线上就会出现图片加载失败。
这个坑很隐蔽，因为本地开发服务器一般不区分大小写。遇到图片或资源 404，第一反应应该是检查文件名的大小写是否完全一致。
6.2 push 之后等不到更新
有时候你推送了代码，刷新页面还是老样子。排除缓存问题后，大概率是构建流程还没结束。GitHub Pages 的构建虽然不是秒级完成，但通常也就一两分钟。你可以在仓库的 Actions 页面看进度，如果构建失败，页面上会直接显示红色错误。
还有一个比较容易忽略的点：如果你使用的是自定义 GitHub Actions 部署流程，记得在仓库 Settings -> Actions -> General -> Workflow permissions 中把权限设为Read and write permissions，否则推送构建产物到 gh-pages 分支时会报权限错误。
6.3 不要把秘密文件提交进仓库
因为是公开仓库，你的 GitHub Pages 站点本身就是公开的。任何提交到仓库的内容，都会直接暴露在互联网上。代码中的 API Key、数据库连接串、个人敏感信息，绝对不要提交进去。
我见过不少人在早期项目里把环境变量硬编码在代码里，结果部署后直接被搜索引擎抓走，非常被动。正确的做法是敏感信息放在 GitHub Secrets 中，构建时通过环境变量注入，或者本地配置文件加入.gitignore，强制不纳入版本管理。
7. 写在最后的个人体会
我前前后后用 GitHub Pages 搭过不同类型的站点，有纯手工写 HTML 的个人主页，有基于 Jekyll 的博客，有用 Vite 构建后自动部署的前端项目文档站。每个项目的规模和复杂度不同，但核心逻辑一直没变过：内容以静态文件形式存在，代码仓库就是发布中心，推送即部署。
这套模式非常适合个人项目和中小型团队使用，不花一分钱，就能拥有一个可以长期维护、随时迁移的站点。如果你之前一直只想不做，建议今天就去建一个仓库，放上一个最简单的index.html，先把跑起来的感觉找到，再慢慢把内容和结构填起来。真到上手之后你会发现，最难的部分其实不是技术，而是想清楚你要写什么。
本文还有配套的精品资源，点击获取
