全貌：三条腿

先建立一个正确的心理模型：

1. 代码仓库：文章和模板存在 GitHub 的仓库里
2. 构建服务：GitHub Pages 把仓库里的 Jekyll 源码编译成静态 HTML
3. 域名解析：把 你的域名 指向 GitHub Pages 的服务器

三者缺一不可。常见故障大多是”仓库推了但 Pages 没开”或者”Pages 开了但 DNS 没生效”。

前提：本文假设你把站点放在用户主页仓库里，仓库名必须是 你的用户名.github.io。这样博客直接占用根路径，域名配置最简单。

第一步：把文件推上 GitHub

先在 GitHub 网页上新建一个空仓库，名字填 你的用户名.github.io，不要勾选”添加 README”。然后在本机执行：

cd 你的博客目录
git init
git add .
git commit -m "初始化博客"
git branch -M main
git remote add origin https://github.com/你的用户名/你的用户名.github.io.git
git push -u origin main

验证：刷新仓库页面，能看到 _config.yml、_posts、index.html 这些文件。

第二步：开启 Pages

进入仓库的 Settings → Pages：

1. Source 选择 Deploy from a branch
2. Branch 选择 main，目录选 / (root)
3. 点击 Save

等 1~3 分钟，Pages 页面顶部会出现 Your site is live at https://你的用户名.github.io/。

这时先用 GitHub 给的地址访问一次。这一步能打开，说明仓库和构建没问题，后面再折腾域名才有意义。

如果 5 分钟还没好，去 Actions 标签页看 pages build and deployment 的状态；红色叉号点进去看日志，最常见的原因是 _config.yml 语法错误。

第三步：配置 DNS

先明确你要用哪种地址。两种都配是最稳的做法：

方案 A：主域名 example.com（推荐）

在域名服务商的 DNS 管理页面，添加 4 条 A 记录，主机记录都填 @：

方案 B：子域名 www.example.com 或 blog.example.com

添加 1 条 CNAME 记录：

注意：CNAME 的记录值只写到 你的用户名.github.io，末尾不要加 .，也不要加 https://。

顺手加一条 www 跳转

如果你用主域名，通常会再加一条 www 的 CNAME 指向 你的用户名.github.io，然后在 Pages 设置里勾选强制跳转。GitHub 会自动把 www.example.com 301 到 example.com（或反过来，取决于你在 Pages 里填的主域名）。

配置完成后，用命令检查是否生效（DNS 一般 10 分钟到 1 小时）：

nslookup example.com
nslookup www.example.com

第四步：绑定域名

1. 仓库根目录新建一个文件 CNAME（没有后缀），只写一行：

example.com

1. 回到 Settings → Pages → Custom domain，填 example.com，点 Save

保存后，GitHub 会自动把 CNAME 文件改写一遍（所以你本地看到的可能被覆盖，这是正常的）。

1. 等 DNS 检查通过，勾选 Enforce HTTPS

验证顺序：

• http://example.com 能打开
• https://example.com 能打开，且地址栏有小锁
• https://www.example.com 会跳转到主站
• 手机 4G 网络也能打开（排除本地缓存干扰）

第五步：把域名写进 _config.yml

这一步最容易被忘，忘了也不会报错，但分享到社交平台时缩略图会挂掉。

url: "https://example.com"
baseurl: ""

改完提交：

git add _config.yml
git commit -m "配置正式域名"
git push

常见问题排查

打开是 404

• 仓库是不是叫 用户名.github.io？拼写是否完全一致？
• Pages 的 Source 是不是选了 main 分支的 / (root)？
• 仓库里有没有 index.html 或 index.md？

打开显示的是 README

Jekyll 会把仓库根目录的 README.md 当成首页，除非你已经有了 index.html。本站就带了 index.html，如果它不在，检查是不是被误删了。

域名打不开，GitHub 地址正常

几乎都是 DNS 问题。用 nslookup 看解析结果对不对；如果服务商支持，把 TTL 调小（比如 600 秒）再等一会儿。

提示 “Domain is not properly formatted”

CNAME 文件里只能有一行纯域名，不能有 https://、不能有路径、不能有逗号。

HTTPS 选项是灰的

说明 GitHub 还没完成域名验证，通常再等几十分钟即可。如果超过 24 小时，检查 DNS 里有没有多余的 AAAA 记录或冲突的 CNAME。

上线之后

• 每推送一次 main 分支，GitHub 会自动重新构建，通常 1 分钟内生效
• 在 Settings → Pages 页面可以看到每次构建的状态
• 提交文章前建议先本地预览（见 docs/部署指南.md 的”本地预览”一节）

写完这些，网站就算是真正属于你了。

为什么又开一个博客

写作这件事，我断断续续做过很多次。最早是在某个已经关停的平台上，后来是朋友圈的长文，再后来是笔记软件里几百条永远发不出去的草稿。

我后来意识到，问题不在于”写不出来”，而在于”没有读者”——没有读者，写作就变成了自我感动，句子会越来越松，观点会越来越含糊。所以这一次，我决定把笔记搬到公开的地方：

• 有网址，可以随手发给朋友
• 有目录，能看见自己写过什么
• 有 RSS，愿意订阅的人不必天天来看

更重要的是，公开意味着要负责任。一句话写出去，至少要能自圆其说。

这里会写什么

大致是三块内容：

1. 技术笔记：踩过的坑、读过的源码、用过的工具。尽量写成可以照着操作的样子，而不是只留下结论。
2. 读书笔记：书里让我改变想法的段落，以及我为什么不同意作者。
3. 生活随笔：跑步、拍照、做饭，以及一些不成体系的胡思乱想。

我不会保证更新频率，但会保证每一篇都值得发出来——至少对写它的我来说是如此。

你可以怎么读

• 想按主题看，去 分类 页面
• 想按时间翻，去 归档 页面
• 只关心某几个词，用 搜索
• 想第一时间收到更新，订阅 RSS

关于技术实现

这个网站是用 Jekyll 生成、托管在 GitHub Pages 上的静态站点，没有任何后端和数据库。文章用 Markdown 写，提交到 GitHub 后自动构建发布。

顺便说一句，如果你也想搭一个自己的博客，我把完整的部署步骤写在了另一篇文章里：从零把这个博客放到互联网上。

最后，谢谢你来。如果某篇文章恰好帮到了你，或者你不同意我的某个观点，欢迎写信给我。被认真地反驳，是一件很幸运的事。

想写新文章时，建议直接复制这个文件的框架，改掉开头的配置和正文即可。

标题与段落

正文用 ## 作为一级小标题，### 作为二级小标题。右侧的目录会自动抓取它们，所以别跳级（比如从 ## 直接到 ####）。

段落之间空一行。中文排版上，中英文之间、数字与汉字之间会自动保留视觉间距，不需要手动敲空格。

强调与链接

• 加粗 用两个星号
• 斜体 用一个星号
• 删除线 用两个波浪号
• 行内代码 用反引号
• 普通链接 用方括号加圆括号

链接会在新窗口打开（站外链接由脚本自动处理），站内链接直接用相对地址即可。

列表

无序列表用 -：

• 第一项
• 第二项
  • 缩进两个空格表示子项
  • 再一层也可以
• 第三项

有序列表用数字：

1. 先读需求
2. 再写代码
3. 最后写文档

引用

设计不是让东西好看，而是让东西变得更好用。

—— 某个我记不清名字的设计师

引用可以有多段，用空行加 > 分隔即可。

代码

行内代码：执行 bundle exec jekyll serve 启动本地预览。

代码块需要标注语言，这样才有语法高亮：

# 安装依赖并启动本地服务
bundle install
bundle exec jekyll serve --livereload

// 计算阅读时间的小函数
function readingMinutes(words, wpm = 300) {
  return Math.max(1, Math.ceil(words / wpm));
}

console.log(readingMinutes(1500)); // 5

# 统计文章字数
def word_count(text: str) -> int:
    return len(text.replace("\n", "").strip())

代码块右上角有一个”复制”按钮，点一下就能拿走整段代码。

表格

列的对齐方式由表头分隔行里的冒号决定，:---: 表示居中。

图片

图片放在 assets/images/posts/ 目录下，然后用标准的 Markdown 语法引用：

![图片说明](/assets/images/posts/你的图片.jpg)

想加图注，可以用 HTML 的 figure 标签：

<figure>
  <img src="/assets/images/posts/你的图片.jpg" alt="说明">
  <figcaption>图片下方的小字说明</figcaption>
</figure>

点击正文里的图片可以放大查看。

分割线

三个减号就是一条分割线：

提示框

用引用块加粗开头，可以做出提示框的效果：

提示：文章里的所有内部链接都建议用相对路径（以 / 开头），这样以后换域名也不会失效。

需要避免的写法

• ❌ 不要用一级标题 #，它会和文章标题打架
• ❌ 不要直接写两对花括号连起来的模板语法，Jekyll 会尝试解析它（需要展示时用 {{ 转义）
• ❌ 不要手动给标题加锚点，脚本会自动生成
• ❌ 图片不要超过 500KB，最好先压缩

最后

把这篇文章的源码复制一份，重命名为 2026-11-10-你的文章标题.md，改掉开头的 title、date、description，就可以开始写了。

更多细节见仓库里的 docs/写文章指南.md。