从其他系统迁移
把 Jekyll、WordPress、Medium 等旧站内容迁到 Hugo:先判断走内置 importer 还是社区工具,再按「导出 → 转换 → 核对」三步验证,附迁移后必须检查的清单。
开始之前,你需要
- 旧站点的后台或数据库可访问,能导出全部内容。
- 本机已装好 Hugo 并能建起一个空站点。
- 旧站内容已完整备份(迁移工具大多会就地改写或生成大量文件)。
读完之后你能
- 按源系统选出正确路线:Hugo 内置 importer、社区转换工具,还是先导出再手工处理;
- 用
hugo import jekyll跑通一次最小迁移,并核对 front matter、固定链接与静态资源三处结果; - 列出迁移后必须逐项检查的清单,避免上线才发现链接大面积 404;
- 知道旧站 URL 与新站 URL 不一致时,用
aliases或重定向兜住老访客。
接着读:hugo import jekyll · URL 管理 · 目录结构 · 站内搜索
这一页解决什么问题
这一页解决**「我的文章怎么从旧系统搬过来」**。它不追求帮你选一个「最好的工具」,而是让你在动手前就能判断:这次迁移要花多少工夫、哪些东西会丢、搬完之后检查哪几样才算完成。
有两件事必须先说清楚,否则后面几乎一定要返工:
- 迁移工具只负责把文件转成 Hugo 能读的格式,不负责让你的旧链接继续有效。 URL 结构是新旧系统的最大差异,而它决定搜索引擎与老访客还能不能找到页面。要处理这一层,靠的是 URL 管理里的
aliases与固定链接设置。 - 迁移的成败以「构建通过 + 抽查页面 + 链接可达」为准,不以工具输出「Completed」为准。社区工具的维护状态差异很大,工具跑完没报错、内容却是空的,是很常见的结果。
该走哪条路
先看源系统,再看工具是否还活着:
| 源系统 | 首选路线 | 备选 |
|---|---|---|
| Jekyll / Octopress | Hugo 内置 hugo import jekyll,见命令页 |
JekyllToHugo、ConvertToHugo、octohug |
| WordPress | wordpress-to-hugo-exporter 插件导出 Markdown/YAML;内容多、要保 URL 用 wp2hugo |
导出成 Jekyll 格式再用内置 importer;blog2md、wordhugopress |
| Medium | medium2md(一条命令)或 medium-to-hugo(含标签与图片) |
—— |
| Tumblr | tumblr2hugomarkdown 或 tumblr-importr |
Tumblr to Hugo(额外产出重定向用 CSV) |
| Blogger | blogger2hugo(用 Google Takeout 的 .atom 备份) |
blogimport、blogger-to-hugo、BloggerToHugo(仅 Windows)、blog2md |
| DokuWiki | dokuwiki-to-hugo(生成 TOML 头部,可直接塞进 content/) |
—— |
| Drupal / Joomla / Contentful / BlogML | drupal2hugo / hugojoomla / contentful-hugo / BlogML2Hugo |
—— |
判断社区工具还能不能用的三个动作(比看介绍可靠):
- 看最近一次提交:打开工具的仓库,提交列表顶部那条是什么时候。(想从命令行确认,用
git clone --depth 1 <仓库地址>之后执行git log -1 --date=short --format='%ad %s'。) - 看它提到哪些版本:README 与 Issues 里有没有说明支持的 Hugo 版本、以及最近报出的问题。
- 先拿 3–5 篇文章试跑:确认产物能被
hugo构建、正文不空,再决定是否全量转换。
最小可用步骤:用内置 importer 迁移 Jekyll
Jekyll 是唯一由 Hugo 自己提供迁移命令的系统,因此它也是验证「迁移流程长什么样」的最短路径。命令需要两个位置参数,先源目录、后目标目录:
hugo import jekyll ./my-jekyll-site ./my-hugo-site目标目录已经存在且非空时,必须显式允许写入:
hugo import jekyll ./my-jekyll-site ./my-hugo-site --force迁移过程不顺利时,把日志级别调到 debug 再看:
hugo import jekyll ./my-jekyll-site ./my-hugo-site --logLevel debug你应当看到什么:
-
命令退出码为 0,目标目录里出现
archetypes/、content/、data/、layouts/、static/、themes/目录,以及一份配置文件。实测(Hugo v0.167.0,Windows,源站是只有_config.yml与_posts/的最小 Jekyll 项目):配置文件是hugo.yaml,不是hugo.toml;导入的文章落在content/post/下(目录名沿用 Jekyll 的 post 概念),hugo.yaml里写入了从 Jekyll 配置转换来的baseURL、title等项; -
新站点目录下执行构建,退出码为 0:
bashcd ./my-hugo-site hugo --renderToMemory实测(Hugo v0.167.0,Windows,条件同上):刚导入的站点没有主题、
layouts/里也没有任何模板,所以构建虽然退出码为 0,却会为每种页面输出一条WARN found no layout file for "html" for kind "…"。看到这类 WARN 不等于导入失败——它只说明还没有模板可用。要看到真正的 HTML 页面,得先给站点装上主题;hugo import jekyll结束时自己会打印一段添加 ananke 主题的提示,照着做即可(装完主题后文章地址形如/post/<文件名>/); -
文章出现在内容清单里,数量与源站点的一篇文章数大致相符:
bashhugo list all -
装上主题之后,打开构建产物里的任意两篇(
content/post/里的文章地址形如/post/<文件名>/,对应产物是public/post/xxx/index.html),正文不是空的,且标题、日期是原文章的值。若产物里仍然只有index.xml、sitemap.xml这类文件而没有 HTML 页面,说明主题(或layouts/)还没就位,不是导入把内容弄丢了。
以上四条任一不成立,先别继续往下搬——先拿三五篇定位问题,比全量导入后再排查便宜得多。
迁移后必须检查的清单
| 检查项 | 怎么查 | 不合格的表现 |
|---|---|---|
| 文章总数 | hugo list all 的行数与源站文章数对比 |
差了很多:导出不完整,或草稿被排除 |
| 正文完整性 | 在产物里打开几篇最长的文章 | 正文为空、只剩标题;短代码或代码块被吃掉 |
| 前置元数据 | 打开源文件,确认 title/date/tags 等键齐全并与源站对应 |
日期全是迁移当天;标签丢失 |
| 固定链接 | 用源站的一批旧 URL 拼出新站地址逐条打开 | 大量 404 —— 需要配置固定链接与 aliases,见 URL 管理 |
| 静态资源 | 搜索产物里是否还有指向旧域名的 img src |
图片 404、仍从旧站加载 |
| 分类与标签 | 检查 public/tags/、public/categories/ 下的页面 |
标签页为空:源站的分类体系没有映射成 Hugo 的分类法 |
| 构建告警 | hugo --ignoreCache 是否输出 WARNING |
有告警说明部分内容被跳过,逐条处理后再发布 |
只有这一张表全部通过,这次迁移才算结束。搜索引擎收录的是 URL,不是文章,所以固定链接那一行的优先级最高。
Jekyll
另一种做法是使用 Hugo 内置的 Jekyll 导入命令。
- JekyllToHugo
- 一个把 Jekyll 博客文章转换为 Hugo 站点的小脚本。
- ConvertToHugo
- 把博客从 Jekyll 转换到 Hugo。
Octopress
- octohug
- Octopress 到 Hugo 的迁移工具。
DokuWiki
- dokuwiki-to-hugo
- 把 DokuWiki 源页面从 DokuWiki 语法迁移为 Hugo 的 Markdown 语法。它还包含 TODO 插件一类的额外处理。用 Python 3 编写,注重可扩展性。同时会为每个页面生成 TOML 头部。设计目标是让你把 wiki 目录直接复制粘贴进
content目录。
WordPress
- wordpress-to-hugo-exporter
- 一个一键式 WordPress 插件,把所有文章、页面、分类法、元数据与设置转换为 Markdown 和 YAML,可直接放进 Hugo。(注意:如果你在使用该插件时遇到问题,可以把站点导出为 Jekyll 格式,再使用前面提到的 Hugo 内置 Jekyll 转换器。)
- blog2md
- 适用于你的免费 YOUR-TLD.wordpress.com 网站导出的 xml 文件。它还会把已批准的评论连同文章一起保存到
YOUR-POST-NAME-comments.md文件中。 - wordhugopress
- 一个用 Java 编写的小工具,从数据库中导出整个 WordPress 站点,以及存放在本地或远端的资源(例如图片)文件。因此也可以从备份文件进行迁移。支持把多个 WordPress 站点合并为一个 Hugo 站点。
- wp2hugo
- 一个基于 Go 的命令行工具,用于把 WordPress 网站迁移到 Hugo。它会保留原始 URL、GUID、图片 URL、代码高亮、目录以及 WordPress 导航分类。它可以迁移 WordPress 的自定义文章类型、自定义分类法、自定义字段与页面层级。它支持通过 Polylang 或 WPML 翻译的 WordPress 博客。它会导入 WordPress 媒体库数据库及其原始标题与日期。该工具可以下载全部媒体,也可以只下载插入到页面中的媒体。它会把 WordPress 短代码与 Gutenberg 区块转换为 Hugo 短代码,包括图库、图片、音频、YouTube 嵌入、Gist 与 Google Maps。
Medium
- medium2md
- 一个简单的 Medium 到 Hugo 的导出器,一条命令即可导入文章,包括前置字段。
- medium-to-hugo
- 一个用 Go 编写的命令行工具,把 Medium 文章导出为与 Hugo 兼容的 Markdown 格式。会包含标签与图片。所有图片都会下载到本地并正确链接。
Tumblr
- tumblr-importr
- 一个导入器,使用 Tumblr API 生成 Hugo 静态站点。
- tumblr2hugomarkdown
- 把所有 Tumblr 内容导出为 Hugo Markdown 文件,并保留原始格式。
- Tumblr to Hugo
- 一个迁移工具,把你的每篇 Tumblr 文章转换为带正确标题与路径的内容文件。它还会生成一个 CSV 文件,帮助你设置 URL 重定向。
Drupal
- drupal2hugo
- 把 Drupal 站点转换为 Hugo。
Joomla
- hugojoomla
- 这个用 Java 编写的工具读取 Joomla 数据库,把全部内容转换为 Markdown 文件。它会把 Joomla 内部格式的 URL 改为合适的形式。
Blogger
- blogimport
- 把 Blogger 文章导入 Hugo 的工具。
- blogger-to-hugo
- 另一个把 Blogger 文章导入 Hugo 的工具。它还会下载内嵌图片,把它们保存到本地。
- blog2md
- 适用于你的 YOUR-TLD.blogspot.com 网站导出的 xml 文件。它还会把评论连同文章一起保存到
YOUR-POST-NAME-comments.md文件中。 - BloggerToHugo
- 又一个把 Blogger 文章导入 Hugo 的工具。仅限 Windows 平台,且需要 .NET Framework 4.5。使用前请先阅读 README.md。
- blogger2hugo
- 把来自 Google Takeout 的 Blogger 备份文件(
.atom)转换为 Markdown(.md)文件。该工具生成的输出与 Hugo 的content/结构兼容。
Contentful
- contentful-hugo
- 一个根据 Contentful 上的内容为 Hugo 生成内容文件的工具。
BlogML
- BlogML2Hugo
- 一个帮你把 BlogML xml 文件转换为 Hugo Markdown 文件的工具。附件与图片的链接需要用户自行处理。它能让导出 BlogML 文件的博客(例如 BlogEngine.NET)更容易转换为 Hugo 站点。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
hugo import jekyll 报目标目录非空 |
命令默认只写空目录 | 确认真要写入该目录后加 --force;更稳妥的做法是每次都导入到一个全新目录 |
| 只给了一个路径参数,命令报错 | 它需要两个位置参数,顺序是「源目录 目标目录」 | 补全参数;先 pwd 确认两个路径都存在 |
报错 abort: jekyll root contains neither posts nor drafts(实测:Hugo v0.167.0) |
源目录里既没有 _posts/ 也没有 _drafts/——多半指到了导出目录(如 _site/)或某个子目录 |
让第一个参数指向 Jekyll 项目的根目录(含 _posts/ 的那一层);导入前先 ls(Windows 用 dir)确认 |
| 迁移后文章全都跑到同一个目录 | 源系统没有目录层级信息,或文章都是页面包外的散文件 | 按目录结构重建分区,再用 weight 与 cascade 组织,而不是逐篇手工移动 |
构建报 failed to extract shortcode |
旧系统的短代码/宏被原样写进了正文,而新站点没有对应短代码 | 见短代码;批量替换成普通 Markdown,或为它补一个模板 |
| 迁移后旧链接全部 404 | 新旧 URL 结构不同,且没有配置重定向 | 配置固定链接与 aliases,见 URL 管理 |
| 图片显示为破图 | 附件没有被工具下载,正文里仍是旧域名地址 | 用工具提供的「下载媒体」选项,或在源文件里批量替换域名 |
工具跑完显示成功但 content/ 是空的 |
工具与当前版本不兼容,或输入格式不符合预期 | 换用内置命令或另一个工具;先拿三五篇文章试跑,别一次全量转换 |
| 报错看不懂 | 报错来自转换脚本(Python/Java/Go 各自的错误) | 先确认 hugo --renderToMemory 的退出码:为 0 说明站点本身没问题,故障在转换产物或脚本 |