环境变量与评论系统排错：发布前最终清单

这篇文章为什么重要

评论系统最难受的问题不是“完全不会配”，而是：

• 你已经配了，看起来也像成功了
• 但线上某个环境还是不工作
• 问题点可能在代码、环境变量、GitHub 仓库、giscus app、Discussion 分类、映射方式中的任意一个

这篇文章就是把这些点收成一个统一排错入口。

先记住一句话：不是所有评论问题都和环境变量有关

对于当前项目，评论问题有三层来源：

第一层：项目配置

在 site.config.ts 中定义。

第二层：构建期环境变量

通过 PUBLIC_GISCUS_* 注入，在构建时进入站点配置。

第三层：GitHub 仓库侧条件

包括：

• 仓库是否公开
• Discussions 是否开启
• giscus app 是否安装
• category 是否存在
• giscus.json 是否限制了来源

如果你只盯着环境变量，很容易排错排偏。

当前项目支持的 giscus 环境变量清单

推荐模板如下：

# giscus 基础字段
PUBLIC_GISCUS_REPO=owner/repo
PUBLIC_GISCUS_REPO_ID=R_kgDO...
PUBLIC_GISCUS_CATEGORY=General
PUBLIC_GISCUS_CATEGORY_ID=DIC_kwDO...

# giscus 映射与行为
PUBLIC_GISCUS_MAPPING=pathname
PUBLIC_GISCUS_TERM=
PUBLIC_GISCUS_STRICT=1
PUBLIC_GISCUS_REACTIONS_ENABLED=1
PUBLIC_GISCUS_EMIT_METADATA=0
PUBLIC_GISCUS_INPUT_POSITION=top
PUBLIC_GISCUS_LANG=zh-CN
PUBLIC_GISCUS_LOADING=lazy

# giscus 主题
PUBLIC_GISCUS_THEME_LIGHT=light
PUBLIC_GISCUS_THEME_DARK=dark

# 其他评论系统（如需要）
PUBLIC_UTTERANCES_REPO=owner/repo
PUBLIC_UTTERANCES_ISSUE_TERM=pathname
PUBLIC_UTTERANCES_LABEL=comment
PUBLIC_UTTERANCES_THEME_LIGHT=github-light
PUBLIC_UTTERANCES_THEME_DARK=github-dark

PUBLIC_WALINE_SERVER=
PUBLIC_TWIKOO_ENV_ID=

哪些变更必须重新部署

这是构建期项目最常见的误区。

必须重新部署的情况

• 改了任何 PUBLIC_GISCUS_*
• 改了 site.config.ts
• 改了 provider
• 改了评论区相关组件实现

通常不需要重新部署的情况

• 只是到 GitHub 仓库里开启 Discussions
• 只是安装 giscus app
• 只是去 Discussions 后台查看已有 discussion

但如果你改的是：

• category 名称
• category ID
• mapping 策略

那它本质上仍然是站点配置变更，还是要重新部署。

发布前检查清单

每次准备上线前，按下面顺序检查。

一、构建层

1. npm run build 本地通过
2. 站点主要页面可访问
3. 文章页能正常渲染到底部

二、评论配置层

1. comment.provider 是否正确
2. giscus 基础字段是否完整
3. mapping 是否符合当前站点策略
4. themeLight/themeDark 是否合理

三、GitHub 仓库层

1. 仓库是否公开
2. Discussions 是否开启
3. giscus app 是否安装到正确仓库
4. category / categoryId 是否匹配

四、线上验收层

1. 页面是否加载评论 iframe
2. 是否能登录 GitHub
3. 是否能真正发表评论
4. 是否能正确创建/命中 discussion
5. 主题切换是否同步

症状到原因的快速映射

giscus 专项排错顺序

当评论系统是 giscus 时，建议按这个顺序查，不要跳：

第 1 步：看页面提示

当前项目在 Comments.astro 中会对 giscus 做基础校验。
如果缺字段，页面会直接提示缺的是哪一项。

优先看：

• repo
• repoId
• category
• categoryId
• term（仅在 specific / number 下要求）

第 2 步：看浏览器 Console 和 Network

重点看：

• https://giscus.app/client.js 是否加载成功
• iframe 是否成功插入
• 是否有明显跨域、权限或脚本错误

第 3 步：看 GitHub 仓库

确认：

• 仓库是公开的
• Discussions 已开启
• giscus app 已安装到当前仓库
• category 与 categoryId 对得上

第 4 步：看映射策略

当前项目默认推荐：

mapping = pathname
strict = 1

如果你改成以下任意一种，就要重点复查：

• url
• title
• og:title
• specific
• number

这些模式更容易因为域名、标题、term 填写方式导致错绑或重建。

第 5 步：看是否启用了高级限制

如果仓库里用了 giscus.json：

• origins
• originsRegex
• defaultCommentOrder

尤其要确认来源限制有没有把当前域名挡掉。

最常见的 8 个问题

1. 线上页面根本没有评论区

检查：

1. provider 是否是 giscus
2. 当前环境有没有重新部署
3. 页面提示是否已经指出缺失字段

2. 评论区只显示空白区域

检查：

1. giscus.app/client.js 是否成功加载
2. 浏览器是否有脚本错误
3. iframe 是否被浏览器扩展或网络策略拦住

3. 首次评论没有自动创建 discussion

检查：

1. Discussions 是否开启
2. giscus app 是否安装
3. category/categoryId 是否匹配

4. 本地可用，Vercel Preview 不可用

检查：

1. Preview 环境变量是否配置
2. 是否用 url 映射导致域名变了
3. 是否启用了 giscus.json 的来源限制

5. Preview 正常，Production 不正常

检查：

1. Production 环境变量是否独立配置
2. 自定义域名是否在允许来源范围内
3. 是否用了错误的 repo/category 信息

6. 主题切换后评论区颜色不对

检查：

1. themeLight/themeDark 是否填写
2. 当前主题切换是否真正触发
3. 是否把浅色和深色都映射成了同一个主题

7. 多篇文章命中到同一个 discussion

检查：

1. 是否错误使用了 specific
2. term 是否被多篇文章共用
3. 是否使用了不稳定的标题映射

8. 同一篇文章产生多个 discussion

检查：

1. 是否使用了 url
2. 是否站点路由发生过变化
3. strict 是否关闭

发布后建议固定执行的回归动作

以后每次改评论配置，都至少做下面这些回归：

1. 打开一篇已有评论的文章，确认能命中旧 discussion
2. 打开一篇新文章，确认能首次创建 discussion
3. 切换浅色/深色主题，确认 iframe 同步
4. 在 Production 域名下实际评论一次

本篇结论

评论系统排错最怕“看起来像前端问题，其实是仓库问题”或者“明明改了环境变量，却忘了重建”。
你只要牢牢记住下面这条线：

1. 先看页面提示
2. 再看站点配置与环境变量
3. 再看 GitHub 仓库和 giscus app
4. 最后看高级来源限制

大多数 giscus 问题都能很快定位。

系列总结

到这里，你已经完成了评论系统相关的完整闭环：

• 知道为什么项目采用 provider 机制
• 知道为什么默认推荐 giscus
• 能完成从零配置到上线
• 能在出问题时按统一路径定位

后续如果要继续扩展评论能力，可以再考虑：

• utterances 作为回退方案
• giscus.json 的高级控制
• 更细粒度的评论区埋点与交互统计