Hello World !

这篇文章记录本博客的日常维护流程。当前采用以下结构：

• 私有源码仓库：lifan-chen/hexo-blog-source
• 公开部署仓库：lifan-chen/lifan-chen.github.io
• 本地编写和保存 Hexo 源码，GitHub Actions 构建后将静态网页发布到公开仓库

日常操作都应在私有源码仓库中完成。不要把 Markdown、主题源码或配置文件直接提交到公开部署仓库。

一、首次在新电脑上准备环境

需要预先安装 Git 和 Node.js。然后克隆私有源码仓库并安装依赖：

git clone https://github.com/lifan-chen/hexo-blog-source.git
cd hexo-blog-source
npm ci
npm install --global hexo-cli
hexo version

hexo-cli 是全局命令行工具，项目 package.json 中的 hexo 是站点运行所需的引擎，两者用途不同。不要删除项目中的 hexo 依赖，否则本地构建和 GitHub Actions 都会失败。

二、创建一篇新博客

先同步远程源码：

git switch main
git pull --ff-only origin main

创建文章：

hexo new post "My New Post"

Hexo 会创建：

source/_posts/My New Post.md
source/_posts/My New Post/

然后使用 Typora 打开 Markdown 文件并写作。文章开头至少保留 Hexo 的 Front Matter：

---
title: My New Post
date: 2026-09-08 12:00:00
tags:
  - Example
categories:
  - Notes
---

date 应换成实际发布时间。tags 和 categories 可以按需删除或修改。

三、Typora 图片设置和规则

Typora 的图片复制位置设置为：

./${filename}

必须保持 Markdown 文件名和资源目录名完全一致。例如：

source/_posts/My New Post.md
source/_posts/My New Post/diagram.png

Markdown 中对应的图片引用为：

![说明](<./My New Post/diagram.png>)

允许 / 或 Typora 在 Windows 中写入的反斜杠，但推荐统一使用 /。博客中的兼容脚本只处理严格符合以下关联规则的本地图片：

文章：Foo.md
目录：Foo/
引用：./Foo/image.png

如果路径中含有空格，推荐像上面的示例一样用 <...> 包住完整路径。如果重命名 Markdown 文件，也必须同步重命名资源目录并修改图片引用。

如果文件名和目录名不一致，图片不会被自动修正。网络图片、绝对路径、data: 图片，以及不属于当前文章资源目录的图片也不会被处理。

四、本地预览

安装过依赖后，启动本地服务器：

hexo server

浏览器打开终端显示的地址，通常是：

http://localhost:4000/

预览期间修改 Markdown 后通常会自动重新生成。结束预览时在终端按 Ctrl+C。

如果缓存导致显示异常，先清理再启动：

hexo clean
hexo server

发布前如需单独确认能否构建：

hexo clean
hexo generate

生成结果位于 public/，它不需要提交到私有源码仓库。

五、保存文章或博客代码

文章和博客代码使用不同的分支，避免相互影响：

• main：只写文章和管理文章图片。
• dev：修改主题、配置和脚本。

写完文章后，只需要执行：

hexo update-post

该命令只接受 source/_posts/ 中的文章和配套图片改动，会自动同步
origin/main、构建 Cactus 与 Glass、生成提交并推送。如果当前不在
main，或者检测到主题、配置、脚本等代码改动，它会停止发布。

维护博客代码时切换到 dev，验证后再提交：

git switch dev
git add _config.yml themes scripts package.json package-lock.json
git commit -m "Update blog configuration"
git push origin dev

代码在 dev 验证完成后再合并到 main。只有推送到 main 才会触发公开网站更新。

六、发布到公开网站

正常情况下，写完文章后执行下面这条命令就会自动发布：

hexo update-post

它会完成文章提交和源码推送，并自动触发 GitHub Actions 的 Publish Hexo site 工作流。工作流会安装依赖、构建 Hexo，再把 public/ 中的生成结果推送到公开仓库 lifan-chen/lifan-chen.github.io 的 main 分支。GitHub Pages 随后会更新，通常还需要等待片刻并刷新浏览器缓存。

如果自动发布失败，或者需要在没有新提交的情况下重新发布，可以手动重跑：

1. 打开私有仓库 lifan-chen/hexo-blog-source。
2. 进入 Actions。
3. 选择 Publish Hexo site。
4. 点击 Run workflow，分支选择 main，再次确认运行。
5. 等待工作流全部变绿。

现在不要执行以下旧命令：

hexo deploy
npx hexo deploy

项目已经移除了 hexo-deployer-git，发布应统一通过私有仓库中的 GitHub Actions 完成。

七、最常用的完整流程

发布一篇新文章

git switch main
hexo new post "My New Post"
# 使用 Typora 写文章并添加图片
hexo server
hexo update-post

hexo update-post 成功后会自动开始发布。稍后检查线上页面即可。

更新已有文章

git switch main
# 使用 Typora 修改文章
hexo server
hexo update-post

hexo update-post 成功后会自动同步线上网站。

更新博客主题、配置或脚本

git switch dev
git pull --ff-only origin dev
# 修改代码
hexo clean
hexo generate
git status
git diff
# 只暂存本次实际修改的文件
git add <文件或目录>
git commit -m "Update blog"
git push origin dev

推送到 dev 不会发布网站。验证完成后，将 dev 合并到 main 并推送，才会运行 Publish Hexo site。

八、常见问题

PowerShell 提示找不到 hexo

安装或重新安装全局 Hexo CLI：

npm uninstall --global hexo hexo-cli
npm install --global hexo-cli
hexo version

安装后重新打开 PowerShell，再进入博客项目目录执行 hexo server。如果仍然找不到命令，检查 npm 的全局安装目录是否已加入系统 PATH。

本地依赖缺失或换了电脑

在项目根目录执行以下命令，可严格按锁定版本恢复依赖：

npm ci

只有在主动添加、删除或升级依赖，需要同时更新 lock 文件时才使用 npm install。

本地图片不显示

依次检查：

1. Foo.md 和图片目录 Foo/ 是否完全同名。
2. 图片是否真实存在于 source/_posts/Foo/。
3. Markdown 路径是否为 ./Foo/image.png。
4. 文件名大小写是否一致；GitHub Pages 的 Linux 环境区分大小写。
5. 执行 hexo clean 后重新预览或发布。

路径或文章名含空格时，图片引用写成 ![说明](<./Foo Bar/image.png>)。