从 Hexo(AnZhiYu) 迁移到 Hugo(PaperMod) 完整记录

一、先说结论：工作量评估

建议：先迁移 3~5 篇代表性文章，跑通流程后再批量处理。

二、新博客不能用的语法（AnZhiYu / Hexo 专有）

以下标签在 Hugo + PaperMod 中不存在，写上去会原样显示成文本（或报错），必须替换：

2.1 Hexo tag 插件（AnZhiYu 全部标签）

2.2 其它 Hexo / AnZhiYu 专有写法

（无空格），或在 front matter 写 summary:| |{% raw %}/{% endraw %}| Hugo 用{{< … >}}转义 shortcode | | Hexo 的_drafts/目录 | Hugo 用draft: true标记 | | 即刻短文（essay）系统 | ❌ 无对应，需自行实现（可考虑 Hugo 的独立 section） | | 音乐播放器 / APlayer | ❌ 需自行接入第三方 JS | | 首页轮播图 / 置顶卡片组 | ❌ 无对应，可用 PaperMod 的profileMode 或自建布局 | | AI 摘要（ai:字段） | ❌ 无对应，可改写到description` | | 站点统计（不蒜子等） | ❌ 需自行接入 |

2.3 不能用的 front matter 字段

swiper_index、top_group_index、cover_fit、cover_day、cover_night、ai、abbrlink、background、aside、highlight_shrink、copyright / copyright_author / copyright_url / copyright_info、aplayer、mathjax、katex、toc_number、toc_style_simple、sticky、top_img

这些字段写在 Hugo 里不会报错（被忽略），但也没有任何效果，建议清理。

三、新博客支持的语法（怎么写）

3.1 基础 Markdown（完全通用）

# 一级标题
## 二级标题

**加粗**、*斜体*、~~删除线~~、`行内代码`、[链接](https://example.com)

- 无序列表
- 第二项
  - 嵌套

1. 有序列表

- [x] 已完成任务
- [ ] 未完成任务

| 表头 | 表头 |
|---|---|
| 单元格 | 单元格 |

> 引用块

---

3.2 PaperMod 自带 shortcode

3.3 Hugo 内置 shortcode

3.4 本项目已额外配置好的语法（实测可用）

提示框（对标 AnZhiYu 的 {% note %}，用短代码，内容支持 Markdown）：

{{< note info >}}
信息提示，支持 **加粗**、`代码`、[链接](url)
{{< /note >}}

{{< note success >}}成功提示{{< /note >}}
{{< note warning >}}警告提示{{< /note >}}
{{< note danger >}}危险提示{{< /note >}}
{{< note primary >}}重点提示{{< /note >}}

{{< note info "自定义标题" >}}
带标题的提示框（第二个参数是标题）
{{< /note >}}

⚠️ 不建议用 <div class="note info"> 的 HTML 写法：块级 HTML 内部的 Markdown 不会被解析（CommonMark 规范行为），加粗会原样显示成星号。

行内高亮（对标 {% label %}）：

<mark class="hl red">红色重点</mark>
<mark class="hl green">绿色</mark>
<mark class="hl blue">蓝色</mark>
<mark class="hl yellow">黄色</mark>
<mark class="hl purple">紫色</mark>

两栏对比（对标 {% tabs %} 的静态替代）：

<div class="columns">
<div>
<h4>方案 A</h4>
<p>内容…</p>
</div>
<div>
<h4>方案 B</h4>
<p>内容…</p>
</div>
</div>

数学公式（KaTeX）：

行内：$E = mc^2$

单行独立公式（推荐日常使用）：
$$E = mc^2$$

多行 / 复杂公式（矩阵、多行推导必须用这个）：
{{< math >}}
\begin{pmatrix}
a & b \\
c & d
\end{pmatrix}
{{< /math >}}

⚠️ 重要：多行公式不要直接写多行 $$——Markdown 解析器会把 \end{pmatrix} 这类行误判成标题，导致公式破损。多行公式一律用 {{< math >}} 包裹。

Mermaid 流程图（直接用代码块，无需记短代码）：

```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[结束]
```

时序图、甘特图、类图等所有 Mermaid 图表类型都支持。

3.5 开启数学公式的两种方式

文章 front matter 里任意一种写法都会自动加载 KaTeX：

math: true          # 显式开启

或者正文里出现 $$ 也会自动检测开启。

四、推荐的创作语法组合

日常写作最有价值的四件套：

五、front matter 迁移对照表

六、迁移操作步骤

1. 复制文章

# 在 Hexo 项目里（blog-demo/source/_posts/）
cp 某篇文章.md Z:/ugoblog/content/posts/

2. 调整 front matter

• updated → lastmod
• cover: /img/x.webp → cover.image: "/images/x.webp"
• 多级 categories 拆成一维
• 删除无对应字段

3. 替换正文标签

4. 迁移图片

# Hexo: blog-demo/source/img/  →  Hugo: Z:/ugoblog/static/images/
cp -r blog-demo/source/img/* Z:/ugoblog/static/images/

正文里的 /img/xxx.webp 改成 /images/xxx.webp。

5. 本地预览

cd Z:/ugoblog
hugo server -D        # 含草稿预览，浏览器打开 http://localhost:1313

6. 构建发布

hugo --gc --minify    # 产物在 public/ 目录

七、常用命令速查

hugo new content posts/我的新文章.md   # 新建文章（用 archetypes/default.md 模板）
hugo server -D                         # 本地预览（含草稿）
hugo server --bind 127.0.0.1 -p 1313   # 指定端口
hugo --gc --minify                     # 构建（清理缓存 + 压缩）
hugo --gc --minify --buildFuture       # 构建含未来日期的文章
hugo list all                          # 列出所有文章及 URL
hugo config                            # 查看当前生效的完整配置

⚠️ 注意：front matter 里 date 若是未来时间，默认不会构建（buildFuture: false）， 表现为「文章明明写了却不出现在页面上」。要么改成过去时间，要么加 --buildFuture。

八、关键文件说明

九、迁移后的功能对照