升级了博客

2026-10-24 Hexo

博客最早运行在一套比较老的 Hexo 环境上。后来 Mac、Node.js、Hexo 和各种插件都升级了很多代，旧环境虽然还能勉强运行，但越来越依赖历史版本的软件，维护成本也越来越高。

这次借助 AI 彻底换了底层运行环境、Markdown 渲染、数学公式、代码高亮、CSS 构建和响应式布局等架构。还改进了博客的样式，方便今后产出更系统化的文字内容。

新旧区别

旧版大致是：

Markdown
  ↓
Hexo 3.9.0
  ↓
Kramed / 旧版插件
  ↓
PLN 主题
  ↓
Stylus / node-sass / 浏览器端 Highlight.js 等旧链路
  ↓
静态网页

新版大致是：

Markdown
  ↓
Hexo 8.1.2
  ↓
Marked + CJK 兼容处理
  ↓
hexo-math / Hexo 内置 Highlight.js
  ↓
PLN EJS 模板
  ↓
Dart Sass 编译 SCSS
  ↓
静态 HTML + CSS + 少量 JavaScript
  ↓
GitHub Pages

最大的区别不是页面看起来完全不同，而是生成网页的链路更简单、更现代，也更容易继续维护。维护的便利，除了架构，还体现在 AI 时代特有的 Checkpoint 文件 AI_CONTEXT.md。每次改动只需提交文件并表示：

这是项目 Checkpoint。请先阅读了解架构和设计约束。

就能再次安全可靠地出发。

Node.js 和 Hexo

旧版最后使用的本地环境是：

Node.js 13.14.0
npm 6.14.4
Hexo 3.9.0
hexo-cli 2.0.0

在 Apple Silicon Mac 上，这套环境实际依赖过 x64 / Rosetta。

新版改为：

Node.js 24 LTS
Hexo 8.1.2
hexo-cli 4.3.2

新的终端命令

写文章：

cd ~/blog                 # 进入博客目录
nvm use                   # 依据 .nvmrc 文件切换到对应的 Node.js 版本
npx hexo new "new post"   # 创建新博文 - 链接格式 /2026/10/24/new-post/

# npx 代表调用项目对应版本的 hexo ，和项目依赖严格一致，避免不兼容
#（先运行当前目录中的 hexo ，没有就临时下载对应版本，执行完自动清理）

本地预览效果：

cd ~/blog
nvm use

npm run build  # package.json 设置了 "build": "hexo clean && hexo generate"
npx hexo s     # 启动服务器，在 http://localhost:4000/ 预览博客

如果改了 PLN 主题内容，则需要先更新 m.min.css 再 npm run build：

npm run css   # package.json 设置了 "css": "sass ... .../css/m.min.css"
npm run build
npx hexo s

提交源码

如果只是新增或修改文章：

cd ~/blog

git status
git add source
git commit -m "Update blog posts"
git push origin master

修改 PLN 后要 commit 两次，push 两次：

第一次，先提交 PLN：

cd ~/blog/themes/pln

git status
git add -A
git commit -m "Update PLN theme"
git push origin HEAD

第二次，回到 blog 提交：

cd ~/blog

git add themes/pln
git commit -m "Update PLN theme revision"
git push origin master

必须先 push PLN，再 push blog 的 submodule pointer。

更新网站 - GitHub Pages

博客源码仓库和最终网页不是同一个东西。日常发布可以理解为两步：

Git push
→ 保存博客源码

Hexo deploy
→ 更新 GitHub Pages 网页

Hexo 会把生成后的静态网站（各种 .html 文件）部署到：

git@github.com:chpwang/chpwang.github.io.git

发布：

cd ~/blog
nvm use        # 依据 .nvmrc 文件切换到对应的 Node.js 版本

npm run build  # package.json 设置了 "build": "hexo clean && hexo generate"
npx hexo d     # 部署静态网页到 GitHub Pages

发布后打开博客链接检查最终线上效果。

新 Mac 从零恢复环境

打开终端先安装 Command Line Tools（Git 等工具）：

xcode-select --install

安装 Hombrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

须完成安装器末尾打印的 Next steps 配置，使 brew 可以使用。Apple Silicon Mac 通常执行以下两行；Intel Mac 请按安装器提示改为 /usr/local/bin/brew：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

检查：

brew --version
git --version

安装 iTerm2、Fish Shell、GitHub CLI（仍在 zsh）

brew install fish gh
brew install --cask iterm2

将 Fish 设为登录 shell（需输登录密码）：

FISH_PATH="$(brew --prefix)/bin/fish"
grep -Fxq "$FISH_PATH" /etc/shells || echo "$FISH_PATH" | sudo tee -a /etc/shells
chsh -s "$FISH_PATH"

关闭旧 Terminal，打开 iTerm2，确认进入 fish：

echo $version

添加路径，让 fish 始终能找到 Homebrew：

# Intel Mac 则为 `/usr/local/bin /usr/local/sbin`
fish_add_path /opt/homebrew/bin /opt/homebrew/sbin

在 fish 中安装 nvm.fish（nvm 命令）

curl -sL https://raw.githubusercontent.com/jorgebucaran/fisher/main/functions/fisher.fish | source; and fisher install jorgebucaran/fisher
fisher install jorgebucaran/nvm.fish

此时先不要随意安装最新 Node。项目根目录的 .nvmrc 有记录；等克隆完成后在项目目录使用 nvm install，会自动安装正确的 Node 主版本。

连接 GitHub，并配置 Git 作者身份

gh auth login --git-protocol ssh --web

根据终端提示，在浏览器中登录有权访问 Blog、PLN、Pages 仓库的 GitHub 账户，并允许 gh 创建／上传 SSH 公钥（如出现提示）。无需手工复制 SSH key 到网页。然后检查：

gh auth status

从旧电脑读取原来的作者姓名和邮箱（git config --global user.name、git config --global user.email），在新电脑设置相同信息：

git config --global user.name "你的 Git 提交姓名"
git config --global user.email "你的 Git 提交邮箱"

克隆 Blog，并取回 PLN 子模块：

cd ~    # 切换到目标目录，即希望 blog 文件夹放的位置
git clone --recurse-submodules git@github.com:chpwang/blog.git blog
cd ~/blog

--recurse-submodules 会在克隆 Blog 的同时取回 Blog 当前提交所指向的 PLN 版本。不要单独把最新版 PLN master 强行覆盖进去。

确认：

git status -sb
git submodule status
git -C themes/pln status -sb

子模块默认可能显示 HEAD detached at ...，这是 Git 通过精确 commit 还原子模块时的正常情况。仅为了写文章和发布，无须将 PLN 强行切回 master；以后真的要修改 PLN 时，先检查其分支和指针再切换。

如果首次克隆因子模块网络问题未成功，可在 Blog 根目录执行：

git submodule update --init --recursive

安装正确 Node、依赖，生成网站并本地预览

cd ~/blog
nvm install     # 读取 .nvmrc（Node 24）并安装/启用
nvm use         # 依据 .nvmrc 文件切换到对应的 Node.js 版本

npm ci          # 根据 package-lock.json 精确安装依赖（Continuous Integration）
npm run build   # hexo clean + hexo generate
npx hexo s      # 本地预览；按 Ctrl+C 结束

在浏览器访问 http://localhost:4000/ 。

验证部署配置并发布：

npx hexo deploy  # 发布更新博客网页

部署成功后访问博客网站。如果 Safari 与 Chrome 的行为不一致，先检查 CSS/JS 缓存，不要立即重做主题。

总结

单台电脑上完整的博文流程如下

cd ~/blog                 # 进入博客文件夹目录
nvm use                   # 切到对应的 Node.js

# 多设备可先同步进度再开始（fast-forward only）
git pull --ff-only

npx hexo new "new post"   # 创建新博文

## 对 source/_posts/new-post.md 文件进行各种编辑 ##

npm run build  # 生成静态网页 - "build": "hexo clean && hexo generate"
npx hexo s     # 本地预览效果

# 保存 - save & push
git add source/_posts                       
git commit -m "Update blog posts"
git push origin master

## 若更改了主题样式 pln 则要两个仓库依次 commit/push

# 第一次 commit/push
cd ~/blog/themes/pln
git add -A
git commit -m "Update PLN theme"
git push origin HEAD

# 第二次 commit/push
cd ~/blog
git add themes/pln
git commit -m "Update PLN theme revision"
git push origin master

npx hexo d     # 部署静态网页到 GitHub Pages

其他延伸阅读：
常用的 Markdown 语法、排版和技巧
 常用的 LaTex 语法

`打赏`