搬博客这事，我拖了挺久。原来的系统用了几年，虽然还能跑，但想改点东西越来越费劲。趁着一个周末，把站点迁到了 Hugo，过程比预想中曲折一些，记录几个印象比较深的坑，给后来者省点时间。
先搞清楚要迁移什么
动手之前，得先盘点自己的站点有哪些内容。除了文章本身，还要注意几个容易被忽略的地方：标签和分类、归档页面、RSS 订阅地址、自定义域名配置，以及原来用的评论系统。评论数据一般不在静态站点生成器里，如果依赖第三方服务，可能需要额外处理。
我当时的做法是先列一个清单，把站点的所有页面类型梳理一遍，再逐一验证迁移后是否正常。这一步别偷懒，后面很多问题都是因为前期没盘清楚。
短代码处理比想象中麻烦
原系统里用了一些自定义的嵌入方式，比如视频、代码块、提示框之类。Hugo 有短代码机制可以对应，但不能直接复制，需要针对 Hugo 的语法重写。
这部分问题主要在细节：参数写法不一样，有的需要加引号，有的需要用位置参数，命名也有讲究。一开始我图省事直接粘贴，结果页面渲染出来乱七八糟，只能逐个排查。
建议写一个简单的对照表，把旧系统和新系统的嵌入语法一一对应，尤其是那些带参数的，提前验证过再批量处理。
链接和图片路径是重灾区
迁移后最容易发现的问题就是死链。旧文章里的站内链接、图片引用、附件下载，路径规则和 Hugo 的目录结构不一定匹配，导致大量链接断裂。
处理思路是分两步：先把文章里的相对路径统一成一种格式，然后根据 Hugo 的目录结构调整实际文件位置。如果文章量比较大，写个小脚本批量替换会省力很多。
图片那块还有一个容易遗漏的点——Hugo 对资源文件的处理方式。有些人习惯把图片放在和 Markdown 文件同一个目录下，这需要在配置文件里开启相关选项，否则页面里显示不出来。
配置项看着简单，实际容易踩坑
Hugo 的配置文件刚开始看挺简洁，但有些默认行为可能和预期不一样。比如文章排序规则、摘要生成方式、归档页面的组织逻辑，这些都会影响站点表现。
我的经验是先把官方文档的配置说明通读一遍，尤其是 taxonomy（分类法）相关的部分，比如标签怎么展示、怎么在首页隐藏某些页面。有些地方和旧系统差别很大，想当然地按直觉改了半天，最后发现是某个默认项在起作用。
另外多语言站点的 URL 处理、分页方式这些，如果不确定就先用默认值，跑通再调整。别一上来就堆配置，出问题都不好排查。
主题定制别急着动手
Hugo 的主题机制灵活，但刚开始可以先用现成主题。等基本迁移完成、内容都正常渲染之后，再考虑定制也不迟。
我在这一步栽过跟头：想着边迁移边美化，结果在主题文件里改了一堆乱七八糟的东西，反而分不清是内容问题还是样式问题。后来索性重置主题、重新按需修改，才把问题理清楚。
主题定制时留意 Hugo 的模板覆盖规则，搞清楚哪些文件可以被 override，哪些要直接复制出来改。不然改完发现不生效，容易原地懵。
先本地完备再上线
上线前的验收流程值得多做几遍。Hugo 的本地构建非常快，多刷新几遍页面成本很低，但等到部署上线后再改就麻烦了。
我在上线后才发现一个问题：某些页面在本地显示正常，但部署到服务器后样式错乱。最后排查是基地址配置的问题，域名和本地地址的路径不同导致的。这种情况在构建设置里加一个 `–baseURL` 参数就能解决，提前意识到的话，能少折腾半小时。
另外，旧站点的某些访问路径如果还有外部引用，需要做重定向。我有一部分转载文章的外链指向旧地址，最开始没注意，后来通过统计工具发现 404 才知道问题。定时检查一下 404 日志总是值得的。
博客迁移这种事，麻烦是不可避免的，但把自己踩过的坑如实记下来，下次就只走直路了。