简介这是一份基于 Hexo 框架构建的个人网站源码资源托管于 GitHub Pages对应域名 qianhongbo.github.io面向对静态博客搭建、Hexo 使用或 Stylus 样式定制感兴趣的前端学习者与个人站长。压缩包大小约 2.57MB内含 Hexo 配置、主题样式、Markdown 文章及站点资源等核心内容适合作为个人主页或技术博客的参考模板。目前已有 68 人学习下载通过分析该源码可以掌握 Hexo 的常用配置项、Stylus 在主题中的实际用法如变量、嵌套规则、混合等、Markdown 写作到静态页面生成的完整链路以及如何借助 GitHub Pages 实现自动部署。对于计划搭建个人网站或想深入定制 Hexo 主题的读者这份资源可以直接对照学习帮助理解从源码到线上站点的每个环节并可作为二次开发的起始基础。 很多朋友问我你自己平时折腾技术怎么连个个人网站都没有是不是光说不练其实我一直有挂在 GitHub Pages 上的个人站就是输入邮箱或社交账号时不太好意思写全称——qianhongbo.github.io。这串字符看起来不如花钱买的 .com 域名体面但它承载了我好几年折腾博客、代码和生活记录的空间。这篇就聊聊我是怎么从零搭起这个个人网站的包括选型逻辑、建站过程、遇到过的坑以及一些我在正式文档里见不到的实操经验。1. 项目本质拆解先搞明白个人网站“为什么选 GitHub.io”1.1 github.io 是什么它真实解决了什么问题一上来先说清楚github.io 不是独立域名而是 GitHub Pages 服务提供的三级域名。你注册一个 GitHub 账号然后新建一个仓库仓库名字必须叫“用户名.github.io”GitHub 就会自动把这个仓库发布成一个可公开访问的网站地址就是 https://用户名.github.io。它能做的事情比你想象的多。不只是放一份简历还可以挂作品集、技术博客、文档站、工具导航页甚至有些开发者直接拿它做开源项目的官方网站。我之前见过有人把自己的书稿、PPT、数据可视化项目全部放在 github.io 上维护方式就是 Git 提交就像管理代码一样管理内容。再配合 Jekyll、Hexo、Hugo 这类静态站点生成器就能把 Markdown 写的内容自动变成漂亮的网页不需要单独买服务器不需要折腾数据库发布和回滚都跟代码一样干净利落。对我来说它解决的核心问题是三个零成本、零运维、可长期存在。买域名和主机每年多少要花点钱还要担心续费问题自建服务器要考虑抗并发、安全补丁、宕机恢复一个人根本忙不过来。用 GitHub Pages 则把这些全部省掉你只需要关注内容本身。1.2 适合谁用以及什么样的情况建议别用这个方案适合的人群很明显。个人开发者想建技术博客学生党需要展示项目经历设计师想放作品集或者像我一样只是想要一个数字存在感都属于合适的人选。它最大的门槛不是技术而是“愿不愿意持续写点东西”。反过来说如果你是搞电商的、做企业官网的或者网站需要动态交互、用户注册、在线交易、复杂数据库存储那么 GitHub Pages 就不合适。它本质上只能托管静态页面虽然你可以用 JavaScript 对接外部 API 实现动态效果但服务器端逻辑基本没有。别听人吹 github.io 能替代云服务器二者定位完全不同。2. 建站初期整体设计思路小网站也要分步骤规划2.1 内容定位先于技术选型很多人一上来就先问用哪个框架我的建议反过来先想清楚网站要装什么。我的网站定位很简单三个板块博客文章、项目作品集、关于我。博客主要写技术笔记和踩坑经验项目作品集放我已经开源的代码仓库和相关演示链接关于我介绍基本信息和联系方式。这个定位决定了后续所有技术选择。因为我只需要一个能展示内容、支持文章列表和详情页的小站不需要在线编辑后台不需要多用户权限管理那么静态网站生成器就是最优解。如果你像某些大神一样网站还要放读书笔记、播客链接、摄影集那么内容结构就复杂些需要提前规划好目录和板块不然写多了之后整个网站会变得很乱。2.2 为什么最终敲定 Jekyll 而不是 Hexo 或 Hugo选型这事是绕不开的。GitHub Pages 官方原生支持 Jekyll这是它最大的优势。其他平台每次构建还要配置特定的 Actions 流程而 Jekyll 几乎是直接把仓库推到 GitHub站内自动执行构建省去一整套 CI 配置流程。对轻量个人站来说这个“默认顺手”的效果实在重要。Hexo 也有它的生态优势主题好看、插件丰富但在早期需要人在本地装 Node.js 环境发布时还要手动部署生成静态文件。Hugo 则是出了名的快渲染万篇文章都是毫秒级可它的模板语法和我所熟悉的 Markdown 思维差别较大学习成本高些。我最终还是选 Jekyll因为它和 GitHub Pages 的深度整合能够给我节省大量时间也方便以后有精力折腾时直接改仓库跑起来。2.3 初步的目录规划与信息架构网站在动手前我画了个简单的目录结构放在本地备忘录里。大致是首页展示最新文章和项目入口博客按分类列出文章标题和日期项目页放三到四个有代表性的仓库卡片关于页放自我介绍和联系方式。后期加了友链板块和标签页但最初没敢设计得太复杂怕做一半就没了热情。另外我想强调一个点别一开始就在页面上放很多花哨的交互效果。个人网站的本质是内容容器而不是炫耀前端技艺的舞台。保持干净的排版、清晰的信息层级比炫技重要得多。3. 核心实操全过程从仓库创建到域名访问3.1 仓库创建与命名规则这一步错了全盘皆输我把这一步放在最前面因为它是新手最容易踩坑的地方。你必须在 GitHub 上新建一个仓库名字精确为“你的用户名.github.io”不能有多余字符不能改成其他名字。如果你用户名是 qianhongbo那仓库名就必须是 qianhongbo.github.io这个名下的内容会被 GitHub 自动识别并发布。当时我先建了个叫 my-website 的仓库折腾了半天发现访问不了后来才知道命名规则必须严格匹配。现在记住了不是任何仓库都能开 Pages只有以 .github.io 结尾或特定分支开启 GitHub Pages 功能的仓库才行。对于个人主页最省心的是直接拿用户名当仓库名。初始化时我建议勾选添加 README 文件和 .gitignore选 Jekyll 模板这对新手有一个好处仓库不为空可以直接用本地仓库拉取编辑。然后用命令推上去一个默认页面确认网站真正能访问了再开始后续改造。3.2 页面的三件套index.html、样式文件、配置文件早期我把 GitHub Pages 理解成只能做静态页面的“白纸”。其实只要你在仓库根目录放一个 index.htmlGitHub 就会自动把它当作首页展示。也就是说哪怕不会任何静态站点生成器你只用 HTMLCSS 就能搭出一个最简单可访问的网站。一个最小可行的首页只需要这几行!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleqianhongbo 的个人网站/title /head body h1你好我是 qianhongbo/h1 p这里是我的个人网站。/p /body /html但仅用单页 HTML 不适合长期维护写多几篇文章后全都堆在一个文件里会疯掉。所以我转向 Jekyll让本地写 Markdown 文件、推送后自动生成页面。仓库根目录需要新增 _config.yml 配置文件它控制网站全局标题、作者信息、主题等参数。我常用的基础配置长这样title: qianhongbo 的个人网站 author: qianhongbo email: your-emailexample.com description: 记录技术学习与生活思考 baseurl: url: https://qianhongbo.github.io theme: minima注意这里 baseurl 留空表示网站部署在域名根路径上如果以后想部署到某个子路径下这里才需要用斜杠开头写子路径名称。主题用默认的 minima好处是干净、兼容性高写完 Markdown 扔进去效果就还行。3.3 本地调试环境搭建在写东西前先让子弹飞一会儿直接用 GitHub 网页端编辑也不是不行但稍微复杂一点的文章还是本地调试更舒服。Jekyll 本地运行需要 Ruby 环境我在 Windows 上操作绕了不少弯路这里给一套我这个环境实测可行的路径。Windows 用户先安装 RubyInstaller通过 Ruby 自带的 DevKit 一并安装 MSYS2 工具链。然后打开命令行换上国内镜像源再安装 Jekyll不然 gem 源慢得让人怀疑人生gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/ gem install jekyll bundler接着在本地仓库目录安装依赖并启动本地服务bundle install bundle exec jekyll serve浏览器访问 localhost:4000 就可以实时预览。Jekyll 最舒服的一点是修改 Markdown 后刷新页面就能看到效果无需手动重新构建。这个预览速度对博客写作来说太重要了我几乎每次都是本地确认没有排版问题后再推送到远程。3.4 第一篇文章的诞生Markdown 里的 Front Matter 是灵魂Jekyll 里的文章不是随便放个 .md 文件就行的。每篇文章都需要在开头用 YAML 格式写上 Front Matter至少包含布局layout、标题title、日期date三个字段否则可能被当成普通静态文件处理不进入博客文章列表。我的一篇常见文章头是这样的--- layout: post title: 从零搭建个人网站的完整记录 date: 2025-01-12 14:00:00 0800 categories: [随笔, 建站] tags: [github-pages, jekyll] --- 这里是正文内容直接用 Markdown 写就行。重点提醒文件名规范是“年-月-日-标题.md”比如 2025-01-12-first-post.md。日期会直接决定文章的排序和展示。如果你文件名日期写错了可能出现文章不显示或者排序错乱的问题。3.5 交互细节404 页面、favicon 与社交链接一个网站有没有质感往往看细节。我专门做了一个 404.html当访客输入不存在的链接时会看到一段幽默文案和返回首页的按钮这让网站显得没那么“应付”。favicon.ico 我也放了一个浏览器标签栏不再是一张白纸。社交链接方面我在页脚挂了 GitHub、邮件等联系方式但提醒一句如果不希望被爬虫抓到邮箱不要用纯文本直接展示邮箱地址推荐用 JavaScript 动态拼接的方式来反爬。这个细节我是被垃圾邮件轰炸后才学乖的。4. 上线之后那些事自定义域名、HTTPS 与其他玩法4.1 绑定自定义域名背后的原理GitHub Pages 默认的 github.io 域名能用但如果你想拥有自己的独立域名操作也不复杂。先到域名服务商买一个域名我现在用的是自己名字的拼音没有买 com因为预算有限先用了备选后缀然后在 GitHub 仓库的 Settings - Pages 里填入自定义域名GitHub 会提示你创建一条 CNAME 记录指向“你的用户名.github.io”并且在仓库中自动生成一个 CNAME 文件里面就是你的自定义域名。这里有个容易踩的大坑如果你的仓库根目录没有 CNAME 文件每次推送新内容后 GitHub 可能自动把自定义域名设置重置掉。我头两次没注意每次上线后都得重新设置一次后来直接在仓库根目录添加了 CNAME 文件内容就是一行域名之后再也没出过问题。配置完成后GitHub 会自动为自定义域名申请 Lets Encrypt 的证书启用 HTTPS 访问。这个“免费 TLS 证书”是真香省去了手动续期的烦恼。如果你想强制跳转到 HTTPS直接在 Pages 设置里勾选 Enforce HTTPS 就行。4.2 用小工具提升内容发布效率内容一多纯靠手动执行 git add、git commit、git push 三条命令就会烦。我在本地仓库写了一个简单的发布脚本 deploy.sh一条命令完成提交推送git add . git commit -m 更新博客内容 $(date %Y-%m-%d %H:%M:%S) git push origin main另外 Jekyll 自带了一个非常有用的 draft 机制。你不想立刻发布的文章可以放在 _drafts 目录下本地预览时会显示但 push 到远程后不会被部署上去。我会把没写完的文章都扔在 drafts 里写满意了再移动进 _posts。4.3 还可以怎么玩数据看板、自动发布与更多场景如果你对纯静态网站的边界有清晰认识就可以用第三方服务扩展它的能力。例如通过 GitHub Actions 实现定时自动构建和部署确保每次改动到最新代码发布一条流水线通过外部评论服务如 Giscus、utterances给博客文章加上评论区因为静态站本身没有服务器存储评论需要借助 GitHub Issues 来承载或者你也可以把网站当作工具箱嵌入自己的小游戏、编辑器、可视化图表等。我个人试过最实用的一个扩展是给网站加了一个“读书清单”页面数据直接存在仓库里的 JSON 文件中用 JavaScript 读取生成表格。这样的好处是更新内容不需要重新构建页面只要修改数据文件再 push 即可体验上反而更像一个微型前后端分离应用。5. 常见问题排查与避坑速查表我自己在搭建和迭代过程中踩了不少坑这里整理成速查表新上手的朋友可以直接对照排查现象原因解决办法访问返回 404仓库名不是“用户名.github.io”新建名字完全匹配的仓库或在旧仓库 Settings 里重命名修改内容后网站没变化部署有延迟或构建失败等待 1-2 分钟检查仓库 Actions 或 Pages 构建日志自定义域名被重置缺少 CNAME 文件在仓库根目录手动添加 CNAME 文件内容为你的域名HTTPS 无法开启域名解析未生效或证书申请中确认 DNS 的 CNAME 记录已指向用户名.github.io等待数小时文章列表不显示文章Front Matter 缺失或格式错误确保文章开头是合法的 YAML含 layout、title、date 字段本地预览样式正常但线上异常Jekyll 版本与本地不一致使用 GitHub Pages 官方支持的 jekyll 版本参考 remote theme 配置推送成功但仓库没有自动构建默认分支设置不一致确认 Pages 的构建来源选的是当前分支和根目录遇到 404 别慌在脑子里过一遍仓库名对吗、分支对了吗、部署完成了吗。大多数新人问题出在第一步后面都是水到渠成的事。除此之外还有几个细节值得提一下。文件名里尽量不要有中文和特殊符号因为某些工具或插件对路径处理不够友好图片资源建议建一个 assets/img 目录统一存放不要散落各处发布前随手检查一遍文章里的链接是否有效。这些习惯在你写了几十篇之后会明显减少维护成本。6. 从项目到长期资产内容管理和迭代心得网站搭好只是开始难的是持续维护。我给自己定的频率是每两周至少写一篇技术笔记不追求长文几百字记录一个问题的解决过程就行。时间久了回看这些文章真的能拼出一条完整的技术成长路径面试复盘和写述职报告时都有材料支撑。关于网站迭代我的心得是每次只做一个改变。比如这个月统一了标题风格下个月优化了移动端字体大小大版本更新只做主题和排版调整。避免短期内大改框架否则会陷入“折腾网站本身”而放弃内容输出的死循环。另外一个重要的做法是给内容做减法。早期我什么都想放上去导航栏有七八个菜单后来发现访问量最多的还是“最近文章”和“关于我”两栏。于是我把侧边栏代码块删了首页只保留最近十篇文章和项目卡片视觉立刻干净了许多。个人网站的终极价值是让访客最快找到他要的东西而不是感动你自己。根据我个人经验github.io 这类个人网站最迷人的地方不是技术多酷而是它像一块完全由你掌控的数字地皮。你可以在上面种什么完全由你自己决定。我认识一位做前端的朋友把 github.io 做成了自己的实验田所有新学的动画效果都拿上去练手另一位做产品的朋友把它做成公开版的个人产品说明书。每个人都有不同的用法这恰恰是它最有意思的地方。最后再分享一个小技巧一定要把网站提交到搜索引擎收录尤其是百度配合推送和 Google 的 Search Console。你辛辛苦苦写的内容如果没有搜索入口就像在一个空房间认真演讲没人听得到。GitHub Pages 天然对搜索引擎的爬虫还算友好但你主动去提交站点地图会快很多。Jekyll 有 sitemap 插件装上后生成 sitemap.xml提交一次就能长期有效。我的网站还在不断改版中也许下一次你打开 qianhongbo.github.io 的时候看到的已经又换了一副面孔。但这不重要重要的是这个域名背后记录了一路折腾过来的痕迹那才是最值得保留的东西。本文还有配套的精品资源点击获取
从零搭建 GitHub Pages 个人网站：选型、部署与避坑指南
简介这是一份基于 Hexo 框架构建的个人网站源码资源托管于 GitHub Pages对应域名 qianhongbo.github.io面向对静态博客搭建、Hexo 使用或 Stylus 样式定制感兴趣的前端学习者与个人站长。压缩包大小约 2.57MB内含 Hexo 配置、主题样式、Markdown 文章及站点资源等核心内容适合作为个人主页或技术博客的参考模板。目前已有 68 人学习下载通过分析该源码可以掌握 Hexo 的常用配置项、Stylus 在主题中的实际用法如变量、嵌套规则、混合等、Markdown 写作到静态页面生成的完整链路以及如何借助 GitHub Pages 实现自动部署。对于计划搭建个人网站或想深入定制 Hexo 主题的读者这份资源可以直接对照学习帮助理解从源码到线上站点的每个环节并可作为二次开发的起始基础。 很多朋友问我你自己平时折腾技术怎么连个个人网站都没有是不是光说不练其实我一直有挂在 GitHub Pages 上的个人站就是输入邮箱或社交账号时不太好意思写全称——qianhongbo.github.io。这串字符看起来不如花钱买的 .com 域名体面但它承载了我好几年折腾博客、代码和生活记录的空间。这篇就聊聊我是怎么从零搭起这个个人网站的包括选型逻辑、建站过程、遇到过的坑以及一些我在正式文档里见不到的实操经验。1. 项目本质拆解先搞明白个人网站“为什么选 GitHub.io”1.1 github.io 是什么它真实解决了什么问题一上来先说清楚github.io 不是独立域名而是 GitHub Pages 服务提供的三级域名。你注册一个 GitHub 账号然后新建一个仓库仓库名字必须叫“用户名.github.io”GitHub 就会自动把这个仓库发布成一个可公开访问的网站地址就是 https://用户名.github.io。它能做的事情比你想象的多。不只是放一份简历还可以挂作品集、技术博客、文档站、工具导航页甚至有些开发者直接拿它做开源项目的官方网站。我之前见过有人把自己的书稿、PPT、数据可视化项目全部放在 github.io 上维护方式就是 Git 提交就像管理代码一样管理内容。再配合 Jekyll、Hexo、Hugo 这类静态站点生成器就能把 Markdown 写的内容自动变成漂亮的网页不需要单独买服务器不需要折腾数据库发布和回滚都跟代码一样干净利落。对我来说它解决的核心问题是三个零成本、零运维、可长期存在。买域名和主机每年多少要花点钱还要担心续费问题自建服务器要考虑抗并发、安全补丁、宕机恢复一个人根本忙不过来。用 GitHub Pages 则把这些全部省掉你只需要关注内容本身。1.2 适合谁用以及什么样的情况建议别用这个方案适合的人群很明显。个人开发者想建技术博客学生党需要展示项目经历设计师想放作品集或者像我一样只是想要一个数字存在感都属于合适的人选。它最大的门槛不是技术而是“愿不愿意持续写点东西”。反过来说如果你是搞电商的、做企业官网的或者网站需要动态交互、用户注册、在线交易、复杂数据库存储那么 GitHub Pages 就不合适。它本质上只能托管静态页面虽然你可以用 JavaScript 对接外部 API 实现动态效果但服务器端逻辑基本没有。别听人吹 github.io 能替代云服务器二者定位完全不同。2. 建站初期整体设计思路小网站也要分步骤规划2.1 内容定位先于技术选型很多人一上来就先问用哪个框架我的建议反过来先想清楚网站要装什么。我的网站定位很简单三个板块博客文章、项目作品集、关于我。博客主要写技术笔记和踩坑经验项目作品集放我已经开源的代码仓库和相关演示链接关于我介绍基本信息和联系方式。这个定位决定了后续所有技术选择。因为我只需要一个能展示内容、支持文章列表和详情页的小站不需要在线编辑后台不需要多用户权限管理那么静态网站生成器就是最优解。如果你像某些大神一样网站还要放读书笔记、播客链接、摄影集那么内容结构就复杂些需要提前规划好目录和板块不然写多了之后整个网站会变得很乱。2.2 为什么最终敲定 Jekyll 而不是 Hexo 或 Hugo选型这事是绕不开的。GitHub Pages 官方原生支持 Jekyll这是它最大的优势。其他平台每次构建还要配置特定的 Actions 流程而 Jekyll 几乎是直接把仓库推到 GitHub站内自动执行构建省去一整套 CI 配置流程。对轻量个人站来说这个“默认顺手”的效果实在重要。Hexo 也有它的生态优势主题好看、插件丰富但在早期需要人在本地装 Node.js 环境发布时还要手动部署生成静态文件。Hugo 则是出了名的快渲染万篇文章都是毫秒级可它的模板语法和我所熟悉的 Markdown 思维差别较大学习成本高些。我最终还是选 Jekyll因为它和 GitHub Pages 的深度整合能够给我节省大量时间也方便以后有精力折腾时直接改仓库跑起来。2.3 初步的目录规划与信息架构网站在动手前我画了个简单的目录结构放在本地备忘录里。大致是首页展示最新文章和项目入口博客按分类列出文章标题和日期项目页放三到四个有代表性的仓库卡片关于页放自我介绍和联系方式。后期加了友链板块和标签页但最初没敢设计得太复杂怕做一半就没了热情。另外我想强调一个点别一开始就在页面上放很多花哨的交互效果。个人网站的本质是内容容器而不是炫耀前端技艺的舞台。保持干净的排版、清晰的信息层级比炫技重要得多。3. 核心实操全过程从仓库创建到域名访问3.1 仓库创建与命名规则这一步错了全盘皆输我把这一步放在最前面因为它是新手最容易踩坑的地方。你必须在 GitHub 上新建一个仓库名字精确为“你的用户名.github.io”不能有多余字符不能改成其他名字。如果你用户名是 qianhongbo那仓库名就必须是 qianhongbo.github.io这个名下的内容会被 GitHub 自动识别并发布。当时我先建了个叫 my-website 的仓库折腾了半天发现访问不了后来才知道命名规则必须严格匹配。现在记住了不是任何仓库都能开 Pages只有以 .github.io 结尾或特定分支开启 GitHub Pages 功能的仓库才行。对于个人主页最省心的是直接拿用户名当仓库名。初始化时我建议勾选添加 README 文件和 .gitignore选 Jekyll 模板这对新手有一个好处仓库不为空可以直接用本地仓库拉取编辑。然后用命令推上去一个默认页面确认网站真正能访问了再开始后续改造。3.2 页面的三件套index.html、样式文件、配置文件早期我把 GitHub Pages 理解成只能做静态页面的“白纸”。其实只要你在仓库根目录放一个 index.htmlGitHub 就会自动把它当作首页展示。也就是说哪怕不会任何静态站点生成器你只用 HTMLCSS 就能搭出一个最简单可访问的网站。一个最小可行的首页只需要这几行!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleqianhongbo 的个人网站/title /head body h1你好我是 qianhongbo/h1 p这里是我的个人网站。/p /body /html但仅用单页 HTML 不适合长期维护写多几篇文章后全都堆在一个文件里会疯掉。所以我转向 Jekyll让本地写 Markdown 文件、推送后自动生成页面。仓库根目录需要新增 _config.yml 配置文件它控制网站全局标题、作者信息、主题等参数。我常用的基础配置长这样title: qianhongbo 的个人网站 author: qianhongbo email: your-emailexample.com description: 记录技术学习与生活思考 baseurl: url: https://qianhongbo.github.io theme: minima注意这里 baseurl 留空表示网站部署在域名根路径上如果以后想部署到某个子路径下这里才需要用斜杠开头写子路径名称。主题用默认的 minima好处是干净、兼容性高写完 Markdown 扔进去效果就还行。3.3 本地调试环境搭建在写东西前先让子弹飞一会儿直接用 GitHub 网页端编辑也不是不行但稍微复杂一点的文章还是本地调试更舒服。Jekyll 本地运行需要 Ruby 环境我在 Windows 上操作绕了不少弯路这里给一套我这个环境实测可行的路径。Windows 用户先安装 RubyInstaller通过 Ruby 自带的 DevKit 一并安装 MSYS2 工具链。然后打开命令行换上国内镜像源再安装 Jekyll不然 gem 源慢得让人怀疑人生gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/ gem install jekyll bundler接着在本地仓库目录安装依赖并启动本地服务bundle install bundle exec jekyll serve浏览器访问 localhost:4000 就可以实时预览。Jekyll 最舒服的一点是修改 Markdown 后刷新页面就能看到效果无需手动重新构建。这个预览速度对博客写作来说太重要了我几乎每次都是本地确认没有排版问题后再推送到远程。3.4 第一篇文章的诞生Markdown 里的 Front Matter 是灵魂Jekyll 里的文章不是随便放个 .md 文件就行的。每篇文章都需要在开头用 YAML 格式写上 Front Matter至少包含布局layout、标题title、日期date三个字段否则可能被当成普通静态文件处理不进入博客文章列表。我的一篇常见文章头是这样的--- layout: post title: 从零搭建个人网站的完整记录 date: 2025-01-12 14:00:00 0800 categories: [随笔, 建站] tags: [github-pages, jekyll] --- 这里是正文内容直接用 Markdown 写就行。重点提醒文件名规范是“年-月-日-标题.md”比如 2025-01-12-first-post.md。日期会直接决定文章的排序和展示。如果你文件名日期写错了可能出现文章不显示或者排序错乱的问题。3.5 交互细节404 页面、favicon 与社交链接一个网站有没有质感往往看细节。我专门做了一个 404.html当访客输入不存在的链接时会看到一段幽默文案和返回首页的按钮这让网站显得没那么“应付”。favicon.ico 我也放了一个浏览器标签栏不再是一张白纸。社交链接方面我在页脚挂了 GitHub、邮件等联系方式但提醒一句如果不希望被爬虫抓到邮箱不要用纯文本直接展示邮箱地址推荐用 JavaScript 动态拼接的方式来反爬。这个细节我是被垃圾邮件轰炸后才学乖的。4. 上线之后那些事自定义域名、HTTPS 与其他玩法4.1 绑定自定义域名背后的原理GitHub Pages 默认的 github.io 域名能用但如果你想拥有自己的独立域名操作也不复杂。先到域名服务商买一个域名我现在用的是自己名字的拼音没有买 com因为预算有限先用了备选后缀然后在 GitHub 仓库的 Settings - Pages 里填入自定义域名GitHub 会提示你创建一条 CNAME 记录指向“你的用户名.github.io”并且在仓库中自动生成一个 CNAME 文件里面就是你的自定义域名。这里有个容易踩的大坑如果你的仓库根目录没有 CNAME 文件每次推送新内容后 GitHub 可能自动把自定义域名设置重置掉。我头两次没注意每次上线后都得重新设置一次后来直接在仓库根目录添加了 CNAME 文件内容就是一行域名之后再也没出过问题。配置完成后GitHub 会自动为自定义域名申请 Lets Encrypt 的证书启用 HTTPS 访问。这个“免费 TLS 证书”是真香省去了手动续期的烦恼。如果你想强制跳转到 HTTPS直接在 Pages 设置里勾选 Enforce HTTPS 就行。4.2 用小工具提升内容发布效率内容一多纯靠手动执行 git add、git commit、git push 三条命令就会烦。我在本地仓库写了一个简单的发布脚本 deploy.sh一条命令完成提交推送git add . git commit -m 更新博客内容 $(date %Y-%m-%d %H:%M:%S) git push origin main另外 Jekyll 自带了一个非常有用的 draft 机制。你不想立刻发布的文章可以放在 _drafts 目录下本地预览时会显示但 push 到远程后不会被部署上去。我会把没写完的文章都扔在 drafts 里写满意了再移动进 _posts。4.3 还可以怎么玩数据看板、自动发布与更多场景如果你对纯静态网站的边界有清晰认识就可以用第三方服务扩展它的能力。例如通过 GitHub Actions 实现定时自动构建和部署确保每次改动到最新代码发布一条流水线通过外部评论服务如 Giscus、utterances给博客文章加上评论区因为静态站本身没有服务器存储评论需要借助 GitHub Issues 来承载或者你也可以把网站当作工具箱嵌入自己的小游戏、编辑器、可视化图表等。我个人试过最实用的一个扩展是给网站加了一个“读书清单”页面数据直接存在仓库里的 JSON 文件中用 JavaScript 读取生成表格。这样的好处是更新内容不需要重新构建页面只要修改数据文件再 push 即可体验上反而更像一个微型前后端分离应用。5. 常见问题排查与避坑速查表我自己在搭建和迭代过程中踩了不少坑这里整理成速查表新上手的朋友可以直接对照排查现象原因解决办法访问返回 404仓库名不是“用户名.github.io”新建名字完全匹配的仓库或在旧仓库 Settings 里重命名修改内容后网站没变化部署有延迟或构建失败等待 1-2 分钟检查仓库 Actions 或 Pages 构建日志自定义域名被重置缺少 CNAME 文件在仓库根目录手动添加 CNAME 文件内容为你的域名HTTPS 无法开启域名解析未生效或证书申请中确认 DNS 的 CNAME 记录已指向用户名.github.io等待数小时文章列表不显示文章Front Matter 缺失或格式错误确保文章开头是合法的 YAML含 layout、title、date 字段本地预览样式正常但线上异常Jekyll 版本与本地不一致使用 GitHub Pages 官方支持的 jekyll 版本参考 remote theme 配置推送成功但仓库没有自动构建默认分支设置不一致确认 Pages 的构建来源选的是当前分支和根目录遇到 404 别慌在脑子里过一遍仓库名对吗、分支对了吗、部署完成了吗。大多数新人问题出在第一步后面都是水到渠成的事。除此之外还有几个细节值得提一下。文件名里尽量不要有中文和特殊符号因为某些工具或插件对路径处理不够友好图片资源建议建一个 assets/img 目录统一存放不要散落各处发布前随手检查一遍文章里的链接是否有效。这些习惯在你写了几十篇之后会明显减少维护成本。6. 从项目到长期资产内容管理和迭代心得网站搭好只是开始难的是持续维护。我给自己定的频率是每两周至少写一篇技术笔记不追求长文几百字记录一个问题的解决过程就行。时间久了回看这些文章真的能拼出一条完整的技术成长路径面试复盘和写述职报告时都有材料支撑。关于网站迭代我的心得是每次只做一个改变。比如这个月统一了标题风格下个月优化了移动端字体大小大版本更新只做主题和排版调整。避免短期内大改框架否则会陷入“折腾网站本身”而放弃内容输出的死循环。另外一个重要的做法是给内容做减法。早期我什么都想放上去导航栏有七八个菜单后来发现访问量最多的还是“最近文章”和“关于我”两栏。于是我把侧边栏代码块删了首页只保留最近十篇文章和项目卡片视觉立刻干净了许多。个人网站的终极价值是让访客最快找到他要的东西而不是感动你自己。根据我个人经验github.io 这类个人网站最迷人的地方不是技术多酷而是它像一块完全由你掌控的数字地皮。你可以在上面种什么完全由你自己决定。我认识一位做前端的朋友把 github.io 做成了自己的实验田所有新学的动画效果都拿上去练手另一位做产品的朋友把它做成公开版的个人产品说明书。每个人都有不同的用法这恰恰是它最有意思的地方。最后再分享一个小技巧一定要把网站提交到搜索引擎收录尤其是百度配合推送和 Google 的 Search Console。你辛辛苦苦写的内容如果没有搜索入口就像在一个空房间认真演讲没人听得到。GitHub Pages 天然对搜索引擎的爬虫还算友好但你主动去提交站点地图会快很多。Jekyll 有 sitemap 插件装上后生成 sitemap.xml提交一次就能长期有效。我的网站还在不断改版中也许下一次你打开 qianhongbo.github.io 的时候看到的已经又换了一副面孔。但这不重要重要的是这个域名背后记录了一路折腾过来的痕迹那才是最值得保留的东西。本文还有配套的精品资源点击获取
