Gitalk 从 Gridea 迁移到 Hugo 后失效：完整排查与修复记录
背景
博客从 Gridea 全量迁移到 Hugo 之后，页面可以正常访问，但评论区 Gitalk 看起来无法正常工作：
- 页面不报明显错误，但评论区不加载或不显示历史评论。
- 同一篇历史文章没有关联到旧的 issue。
这篇文章记录一次完整的排查与修复过程，方便后续迁移同类站点时复用。
一、先确认旧站 Gitalk 的“真实行为”
旧站（Gridea Notes 主题）Gitalk 核心逻辑是：
id: (location.pathname).substring(0, 49)
也就是：直接使用 URL path（最多 49 字符）作为 Gitalk issue 唯一标识。
这一步很关键，因为如果新站改了 id 算法，历史评论 issue 就会“对不上号”。
二、对比迁移后 Hugo 的实现
迁移后的 Hugo 模板里，发现两个关键差异：
admin被渲染成了字符串，而不是数组。id使用了sha1(RelPermalink)，和旧站规则不同。
线上抓到的实际片段（修复前）大致是：
admin: "[\"margrop\"]",
id: "61a893da1bbe4c35fe4f8120cfc1f5c28f826ada"
这会带来两个问题：
admin类型错误，Gitalk 初始化会异常或行为不稳定。id不兼容旧规则，历史评论无法映射。
三、修复方案
修复目标：兼容旧站行为优先，先把历史评论全部恢复。
1) 修正 admin 渲染类型
Hugo 模板中改为输出真正的 JS 数组：
admin: {{ .admin | jsonify | safeJS }},
2) 恢复旧站 id 规则
从 sha1 改回旧站 path 截断规则：
{{ if gt (len $.RelPermalink) 49 }}
id: '{{ substr $.RelPermalink 0 49 }}',
{{ else }}
id: '{{ $.RelPermalink }}',
{{ end }}
3) 优化前端资源可用性（国内网络）
将 Gitalk 静态资源从 unpkg 切到 jsdelivr：
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gitalk/dist/gitalk.css">
<script src="https://cdn.jsdelivr.net/npm/gitalk/dist/gitalk.min.js"></script>
这一步不是 Gitalk 逻辑必须项，但能显著减少部分网络环境下的加载失败概率。
四、验证步骤
1) 本地构建检查
hugo --cleanDestinationDir
确认生成页面中的 Gitalk 片段已经变为：
admin: ["margrop"],
id: "/post/hello-world/"
2) 上线后源码回查
curl -sL https://blog.margrop.net/post/hello-world/ | rg -n "gitalk|admin:|id:"
确认线上已经是新模板产物，不是旧缓存内容。
3) GitHub API 验证历史 issue 映射
例如校验 Hello World：
curl -sG "https://api.github.com/repos/margrop/margropcomment.margrop.io/issues" \
--data-urlencode "state=all" \
--data-urlencode "labels=Gitalk,/post/hello-world/"
能查到对应 issue，说明历史评论映射恢复成功。
五、发布流程（本次执行）
git add themes/simple/layouts/partials/gitalk.html
git commit -m "fix: restore gitalk compatibility and correct admin config"
git push origin master
bash scripts/deploy_github_pages.sh
本次修复提交：
cae7cbe fix: restore gitalk compatibility and correct admin config
六、结论与经验
这次问题的本质不是“Gitalk 配置丢了”，而是迁移后行为不一致：
id生成规则变更，导致历史评论映射失败。- 模板渲染类型错误，导致
admin不是数组。
迁移评论系统时，优先级建议如下：
- 先锁定旧站的
id规则并保持一致。 - 确认模板渲染后的 JS 类型正确（不要只看模板源代码）。
- 用线上源码 + GitHub API 双向验证，避免“看起来正常”但实际未关联。