前言

Typecho 作为经典的 PHP 博客系统，以轻量简洁著称；而 Halo 作为基于 Java 的现代博客平台，在功能丰富度与扩展性上更胜一筹。对我来说 WordPress 过于臃肿、Typecho 过于简陋，而Halo 恰好处于两者的平衡点。

这段时间自己本地搭建体验后感觉真的不错，就试着研究如何迁移。然而，官方迁移插件在导入 Typecho 备份时无法识别数据，社区方案也各有缺陷。最终，基于 fghwett/typecho_to_halo 项目进行定制改造，实现了远程图床场景下的完美迁移。

所以这篇文章将详细介绍如何将 Typecho 的数据（文章、页面、评论、标签、分类等）完整迁移至 Halo，同时保留远程图床链接并自动提取文章封面图。

方案对比：原项目 vs 本方案

核心差异一览

为什么禁用附件迁移？

对于使用又拍云、七牛云等远程图床的博客，附件迁移反而会造成困扰：

1. 存储冗余：远程图片已具备 CDN 加速，无需重复存储至 Halo
2. 性能损耗：下载再上传的过程浪费迁移时间
3. 链接失效风险：迁移过程中可能导致图片链接断裂

解决方案：保留原始图床链接，直接享受 CDN 加速。

为什么添加自动提取封面图？

Halo 支持为文章设置封面图（头图），能显著提升博客的视觉层次感。本方案通过正则表达式自动识别文章中的第一张远程图片，将其设为封面，省去手动配置的繁琐。

• 自动扫描文章内容中的第一张远程图片
• 将其设置为文章的封面图
• 无需手动一一设置，提升迁移效率

本版本更新内容

基于之前版本（2026 年 4 月 14 日发布），本版本进一步优化了数据迁移的稳定性和用户体验，主要更新包括：

1. 数据去重检查：新增 loadExistingData() 函数，迁移前预加载 Halo 已有数据，通过 slug 对比自动跳过已存在的标签、分类、文章和页面，避免重复导入。
2. 配置完善：更新配置示例，修复目录名称错误，确保与 config-example.yaml 完全一致。
3. 常见问题更新：针对用户反馈，更新了关于数据重复的解答，明确说明工具已具备去重能力。

技术实现：代码改造详解

改造一：禁用附件迁移

文件：apps/migrate/app.go

// 原代码
actions = append(actions, NewAction("迁移附件", app.migrateAttachments))

// 改造后（注释掉该行）
// actions = append(actions, NewAction("迁移附件", app.migrateAttachments))

改造二：新增封面图提取函数

文件：internal/halo/post.go

/**
 * extractFirstImage 从文章内容中提取第一张远程图片URL
 * 支持 Markdown 图片语法：![alt](url)
 * 支持 HTML img 标签：<img src="url">
 * 只提取 http:// 或 https:// 开头的远程图片
 */
func extractFirstImage(content string) string {
    // 匹配 Markdown 图片语法
    mdPattern := `!\[.*?\]\((https?://[^\s\)]+\.(?:jpg|jpeg|png|gif|webp|bmp|svg|ico))`
    mdRe := regexp.MustCompile(mdPattern)
    mdMatches := mdRe.FindStringSubmatch(content)
    if len(mdMatches) > 1 {
        return mdMatches[1]
    }
  
    // 匹配 HTML img 标签
    htmlPattern := `<img[^>]+src=["'](https?://[^"']+\.(?:jpg|jpeg|png|gif|webp|bmp|svg|ico))["']`
    htmlRe := regexp.MustCompile(htmlPattern)
    htmlMatches := htmlRe.FindStringSubmatch(content)
    if len(htmlMatches) > 1 {
        return htmlMatches[1]
    }
  
    return ""
}

改造三：集成封面图至文章迁移

文件：apps/migrate/app.go - migratePosts 函数内

// 提取文章封面图
cover := extractFirstImage(post.Content)

// 创建文章（新增 cover 参数）
postId, err := h.client.AddPost(halo.Post{
    Title:        post.Title,
    Content:      post.Content,
    Slug:         post.Slug,
    Tags:         tags,
    Categories:   categories,
    Status:       status,
    AllowComment: post.AllowComment,
    Cover:        cover,  // 新增封面图字段
}, h.policyName, h.groupName)

改造四：扩展 Post 结构体

文件：internal/halo/post.go

type Post struct {
    Title        string   `json:"title"`
    Content      string   `json:"content"`
    Slug         string   `json:"slug"`
    Tags         []string `json:"tags"`
    Categories   []string `json:"categories"`
    Status       string   `json:"status"`
    AllowComment bool     `json:"allowComment"`
    Cover        string   `json:"cover,omitempty"`  // 新增封面图字段
}

// AddPost 函数内添加封面图设置逻辑
func (c *Client) AddPost(post Post, policyName, groupName string) (string, error) {
    // ... 现有代码 ...
  
    if post.Cover != "" {
        postSetting.Spec.Template = "post"
        postSetting.CustomTemplate = fmt.Sprintf(`{"cover": "%s"}`, post.Cover)
    }
  
    // ... 后续代码 ...
}

迁移工具原理剖析

架构设计

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Typecho DB    │────▶│  typecho_to_halo │────▶│   Halo API      │
│   (MySQL)       │     │   (Go 程序)      │     │   (REST API)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                        │                       │
        ▼                        ▼                       ▼
   - tc_contents           - 数据读取              - 创建文章
   - tc_metas              - 结构转换              - 创建分类
   - tc_comments           - API 调用              - 创建标签
   - tc_users              - 错误处理              - 创建评论
   - tc_relationships       - 日志输出              - 设置封面图

数据流转过程

迁移内容清单

环境准备

版本要求

前置检查清单

• Halo 已安装并正常运行
• 已获取 Halo Personal Access Token（路径：Halo 后台 → 用户 → 个人令牌 → 生成新令牌）
• 确认 Typecho 数据库可远程访问
• 记录 Typecho 表前缀（如 tc_ 或默认的 typecho_）

实操步骤

第一步：获取迁移工具

# 克隆仓库（注意是下划线，非连字符）
git clone https://github.com/NoEggEgg/ty2halo.git
cd typecho_to_halo

第二步：配置文件

# 复制示例配置
cp config-example.yaml config.yaml

config.yaml 配置详解：

更新说明：配置格式已更新，与 config-example.yaml 保持完全一致。新增 prefix 字段，优化了配置结构。

typecho:
  type: mysql
  # ⚠️ 必须以斜杠结尾！否则附件下载会报错：lookup xxx.comfiles: no such host
  baseUrl: https://your-domain.com/
  dsn: "username:password@tcp(host:port)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
  prefix: typecho_ # 数据库表前缀，默认为 typecho_
  
halo:
  host: your-halo-host:8090
  schema: http        # 或 https
  token: "your-pat-token"
  debug: false
  policyName: default-policy
  groupName: ""

fileManager:
  dir: ./_tmp/        # 临时文件目录

第三步：处理非默认表前缀

问题现象：若 Typecho 使用 tc_ 而非默认的 typecho_ 前缀，运行时会报错 Table 'dbname.typecho_metas' doesn't exist。

解决方案：在 MySQL 中创建视图映射

USE your_database_name;

-- 创建视图映射（将 tc_* 映射为 typecho_*）
CREATE OR REPLACE VIEW typecho_metas AS SELECT * FROM tc_metas;
CREATE OR REPLACE VIEW typecho_contents AS SELECT * FROM tc_contents;
CREATE OR REPLACE VIEW typecho_comments AS SELECT * FROM tc_comments;
CREATE OR REPLACE VIEW typecho_users AS SELECT * FROM tc_users;
CREATE OR REPLACE VIEW typecho_options AS SELECT * FROM tc_options;
CREATE OR REPLACE VIEW typecho_fields AS SELECT * FROM tc_fields;
CREATE OR REPLACE VIEW typecho_relationships AS SELECT * FROM tc_relationships;

清理视图（迁移完成后执行）：

USE your_database_name;

DROP VIEW IF EXISTS typecho_metas;
DROP VIEW IF EXISTS typecho_contents;
DROP VIEW IF EXISTS typecho_comments;
DROP VIEW IF EXISTS typecho_users;
DROP VIEW IF EXISTS typecho_options;
DROP VIEW IF EXISTS typecho_fields;
DROP VIEW IF EXISTS typecho_relationships;

第四步：执行迁移

方式一：使用预编译版本（推荐）

# Windows
ty2halo.exe

# Linux / macOS
./ty2halo

方式二：自行编译

go mod tidy
go build -o ty2halo.exe

迁移执行顺序：

1. ✅ 迁移标签
2. ✅ 迁移分类
3. ❌ 迁移附件（已禁用）
4. ✅ 迁移文章（自动提取封面图）
5. ✅ 迁移页面
6. ✅ 迁移评论

验证与验收

登录 Halo 后台核对数据完整性：

常见问题速查

Q1：重复数据如何处理？

现象：多次运行后标签 / 分类重复。

原因：工具未做重复检测。 更新：工具已添加数据去重检查。

解决：

• 在 Halo 后台删除重复数据后重新运行
• 或修改源码添加存在性检查（需重新编译）
• 新增：工具已内置数据去重功能，会先查询 Halo 中已存在的数据（通过 slug 对比），自动跳过已存在的标签、分类、文章和页面。但如果手动删除 Halo 数据后重新迁移，仍然会正常导入。

Q2：附件下载报错 lookup xxx.comfiles: no such host

原因：baseUrl 缺少末尾斜杠，导致 URL 拼接错误。

解决：确保 baseUrl 以 / 结尾，如 https://example.com/。

Q3：表前缀不匹配

解决：使用上述数据库视图方案，或修改源码中的表名常量。

Q4：如何恢复附件迁移功能？

如需将附件下载至 Halo 本地（不推荐远程图床场景）：

// apps/migrate/app.go
// 取消注释以下行
actions = append(actions, NewAction("迁移附件", app.migrateAttachments))

Q5：封面图提取规则是什么？

总结

通过定制化的 ty2halo 工具，我们实现了：

后续

这篇文章会持续更新，因为迁移后还有各种其他问题需要调试，比如固定链接等，有点小麻烦。

最后更新：2026 年 4 月 20 日（添加数据去重检查等优化）

参考资源

• 仓库地址：https://github.com/NoEggEgg/ty2halo
• 原项目仓库地址：https://github.com/fghwett/typecho_to_halo
• Halo 官方文档：https://docs.halo.run
• Typecho 官方网站：https://typecho.org

‍