简介一份依托代码托管平台静态页功能的轻量级站点源码包面向网页前端和静态博客初学者可帮助快速理解个人站点从内容组织到发布上线的最小实现整体结构非常精简。压缩包共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 langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.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 快速搭建博客如果你不想从零写 HTMLGitHub 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 自定义域名与 HTTPSgithub.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 下 CmdShiftRWindows 下 CtrlF5排除本地缓存。有时候不是构建失败而是 GitHub 的 CDN 缓存还在旧版本这种情况等几分钟通常会恢复。4.3 关于 404 页面GitHub Pages 很贴心地支持自定义 404 页面。在仓库根目录添加一个404.html访问不存在的地址时就会自动展示这个页面。我建议每个站点都配上一个既能提升体验也显得专业。一个最普通的 404 页面可以这样写!DOCTYPE html html langzh-CN head meta charsetUTF-8 title页面不存在/title /head body h1404/h1 p找不到这个页面可能是地址写错了。/p pa href/回到首页/a/p /body /html4.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/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install and Build run: | npm install npm run build - name: Deploy uses: peaceiris/actions-gh-pagesv4 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先把跑起来的感觉找到再慢慢把内容和结构填起来。真到上手之后你会发现最难的部分其实不是技术而是想清楚你要写什么。本文还有配套的精品资源点击获取