从零开始发布一篇博客：完整步骤指南

本博客使用 Hexo 8 和 Icarus 主题搭建，分为英文和中文两个站点。本文按顺序列出从一篇空白文章到正式上线的每一步，所有命令都对应本博客的实际环境。

博客的组织方式

	英文博客	中文博客
文件夹	~/projects/testblog	~/projects/testblog/zh-CN
文章目录	source/_posts/	zh-CN/source/_posts/
配置文件	_config.yml、_config.icarus.yml	zh-CN/_config.yml、zh-CN/_config.icarus.yml
线上地址	https://songchen.science/blog/	https://songchen.science/blog/zh-CN/

Hexo 会把 source/_posts/ 里的 Markdown 文件生成为静态网站。脚本 build.sh 负责构建两个博客，把结果复制到 GitHub Pages 仓库 ~/projects/song.io 并推送，网站随之更新。

按文章的语言选择博客。除非特别说明，下面的命令都在该博客的文件夹中运行。

第 0 步：一次性准备

只有在新电脑上，或缺少某个组件时才需要做。

1. Node.js 24（Hexo 8 需要 Node 20.19 或更高版本）。它已经是 nvm 的默认版本，可以这样检查：

   node --version                            # 应输出 v24.x
   nvm install 24 && nvm alias default 24    # 仅在版本不对时运行

2. 安装博客依赖，每个博客各一次：

   cd ~/projects/testblog && npm install
   cd ~/projects/testblog/zh-CN && npm install

3. 把相册上传密码存入 macOS 钥匙串。build.sh 在构建博客之前会先上传相册，找不到这个密码就会停止。这条命令会要求输入密码（输入的内容不会显示），所以要在真正的终端窗口里运行：

   security add-generic-password -U -a "$USER" -s gallery-sftp -w

4. 可选：pandoc，只在从链接导入文章时需要（见下文”捷径”一节）：brew install pandoc。

第 1 步：创建文章

进入博客文件夹并创建文章：

cd ~/projects/testblog/zh-CN    # 英文博客：cd ~/projects/testblog
TZ=Asia/Shanghai npx hexo new post "文章标题"

TZ=Asia/Shanghai 让命令使用北京时间，与博客配置一致（Asia/Shanghai 是北京时间的标准名称）。如果省略它，而电脑的时钟设在其他时区（例如人在法国时），文章时间会偏差几个小时。

Hexo 会按标题生成两样东西：

• source/_posts/文章标题.md：文章本身
• source/_posts/文章标题/：一个空文件夹，用来放这篇文章的图片

第 2 步：填写 Front Matter

文件开头两行 --- 之间的部分叫 Front Matter。一个填写好的示例：

---
title: 文章标题：中文冒号不用加引号
date: 2026-10-23 11:30:00
tags:
  - python
  - data-science
categories:
  - - Python
    - Tools
cover: https://example.com/banner.jpg
thumbnail: https://example.com/icon.png
---

各字段的作用：

• title：文章标题。如果包含英文冒号加空格（: ），要用引号括起来。
• date：发表时间，使用北京时间。它决定文章在首页和归档中的顺序。2026 年 10 月 24 日之前的文章按巴黎时间填写，保持原样即可。
• tags：关键词。尽量沿用已有标签：概念用小写加连字符（machine-learning），专有名词保留正常大小写（PyTorch）。
• categories：嵌套列表。上面的示例表示分类 Python > Tools。
• cover：文章顶部和首页卡片上的横幅图片。留空则不显示。
• thumbnail：侧边栏”最新文章”列表中的小图，可选。
• abbrlink：由 Hexo 自动添加，构成文章地址（/posts/<abbrlink>/）。发布后不要修改，否则旧链接和评论都会失效。
• abstract 和 password：只用于加密文章（第 4 步）。

第 3 步：撰写正文

在 Front Matter 下方用 Markdown 写正文。

标题： 用 ## 写章节、### 写小节，侧边栏的目录由它们生成。

摘要： 在开头一段之后单独一行写 <!-- more -->。首页只显示它上方的内容，并附上阅读全文的链接。

图片： 把图片复制到文章的同名文件夹（source/_posts/文章标题/），然后只写文件名：

![实验装置](setup.png)

网络图片可以直接使用完整网址。

代码： 用三个反引号围住代码，并写上语言名称，即可获得语法高亮：

```python
print("hello")
```

链接和表格 使用普通的 Markdown 写法，也可以直接写 HTML。

**注意正文中的 {{、{% 或 {#**，例如 Vue 或 Jinja 代码片段。Hexo 会把它们当作模板标签，导致构建失败或内容错乱。请在 Front Matter 中加上 disableNunjucks: true，本文就是这样做的。

第 4 步（可选）：加密文章

在 Front Matter 中加入密码和摘要：

password: 自己设定的密码
abstract: 输入密码前显示的简短介绍。

读者输入密码之前只能看到摘要。带有 encryptAsDiary 或 encryptAsTips 标签的文章会自动加密，使用 _config.yml 中 encrypt: 下设置的密码。

第 5 步（可选）：先存为草稿

npx hexo new draft "我的草稿"                  # 存到 source/_drafts/
TZ=Asia/Shanghai npx hexo publish 我的草稿     # 移到 source/_posts/ 并写入日期

中文博客的配置中设置了 render_drafts: true，草稿也可能被构建并发布出去。未完成的中文文章请放在 source/ 之外，或把这项设置改为 false。

第 6 步：本地预览

在博客文件夹中运行：

npx hexo server

然后打开：

• 英文博客：http://localhost:4000/blog/
• 中文博客：http://localhost:4000/blog/zh-CN/

保存文件后刷新页面即可看到更新。检查标题、”几分钟前发表”的时间、各级标题、图片、代码块、表格，以及首页上的摘要。

如果要同时运行两个博客，第二个换一个端口：npx hexo server -p 4001。发布之前按 Ctrl+C 停止服务器。

第 7 步：发布

在主文件夹中运行 build.sh，并从钥匙串读取相册密码：

cd ~/projects/testblog
GALLERY_SFTP_PASSWORD="$(security find-generic-password -a "$USER" -s gallery-sftp -w)" ./build.sh

build.sh 会依次：

1. 构建相册并上传有改动的照片；
2. 把友情链接复制到中文博客；
3. 构建中文博客，然后构建英文博客；
4. 把两个博客复制到 ~/projects/song.io；
5. 提交并推送到 GitHub。

推送后一两分钟，GitHub Pages 就会更新。如果网站一直显示旧内容，把命令末尾的 ./build.sh 换成 ./build.sh --clean 再运行一次，它会先清除 Hexo 的缓存和旧的构建结果。

第 8 步：检查线上文章

在文章的 Front Matter 中找到 abbrlink:（由 Hexo 自动添加）。文章地址是：

• 英文：https://songchen.science/blog/posts/<abbrlink>/
• 中文：https://songchen.science/blog/zh-CN/posts/<abbrlink>/

同时确认文章出现在首页，以及对应的分类和标签页面中。

捷径：从链接转载文章

把网上已有的文章变成注明出处的转载文章：

cd ~/projects/testblog
node automation/link-to-post.mjs "https://example.com/some-article"

脚本会下载文章、转换为 Markdown、把图片保存到文章文件夹、加上来源标签和署名，并按文章语言放进对应的博客。之后从第 2 步（标签和分类）和第 6 步继续。加上 --dry-run 只预览结果，加上 --blog zh 或 --blog en 可以自己指定博客。

常见问题

问题	原因与解决方法
Set GALLERY_SFTP_PASSWORD before running the gallery upload.	没有传入密码。先保存一次密码（第 0 步），再使用第 7 步的命令。输入密码的提示只能在真正的终端窗口中使用，聊天窗口的 Run 按钮无法输入。
新文章的时间偏差几个小时	date 不是北京时间。修改 Front Matter 中的日期，并用 TZ=Asia/Shanghai 创建文章。
Hexo 一启动就报 ERR_REQUIRE_ESM 或其他错误	Node 版本不对。运行 nvm use 24。
出现 Template render error，或含 {{ 的文字消失	在 Front Matter 中加上 disableNunjucks: true。
图片不显示	图片不在文章的同名文件夹中，或文件名（包括大小写）不完全一致。
预览时提示端口 4000 已被占用	已有服务器在运行。先停止它，或运行 npx hexo server -p 4001。
线上网站还是旧内容	等两分钟再刷新。如果仍是旧的，用 --clean 重新发布。

速查清单

cd ~/projects/testblog/zh-CN                            # 英文博客：~/projects/testblog
TZ=Asia/Shanghai npx hexo new post "标题"               # 1. 创建
# 2-3. 填写 Front Matter、撰写正文、把图片放进文章文件夹
npx hexo server                                         # 6. 预览，然后按 Ctrl+C
cd ~/projects/testblog
GALLERY_SFTP_PASSWORD="$(security find-generic-password -a "$USER" -s gallery-sftp -w)" ./build.sh   # 7. 发布

最后打开文章地址检查（第 8 步）。