纯静态 Changelog 页面应使用语义化 HTML 结构：每个版本用 <section> 包裹，<h2> 或 <h3> 标注带 id 的版本号（如 #v2.1.0），变更项用 <ul><li> 列出，前缀图标（如 ✨、?）提升可读性；禁止 <pre><code> 日志 dump，须人工或脚本生成结构化内容，并通过哈希注释或文件名版本控制缓存。
Changelog HTML 页面该用什么结构写
纯静态 Changelog 页面不需要框架或构建工具，用标准 HTML + 语义化标签就能清晰表达版本演进。核心是让每个版本块可定位、可链接、可扫描。
必须用 <section> 包裹每个版本，用 <h2> 或 <h3> 标注版本号（如 v2.1.0），并给 id 属性——这样外部能通过 #v2.1.0 直接跳转，文档、PR、内部沟通都依赖这个锚点。
变更条目统一用 <ul> + <li>，不建议用表格或 div 堆砌：前者语义不清，后者难维护。每条变更前加图标或前缀（如 ✨ 新增、? 修复）比纯文字更易扫读，但这些只是文本，不要引入 SVG 或 JS 控制显示逻辑。
怎么让 changelog.html 自动同步 Git 提交记录
手动更新 HTML 的 Changelog 很快就会过期。真正可持续的做法是生成式流程：用脚本解析 git log 或 git tag，输出 HTML 片段。
立即学习“前端免费学习笔记（深入）”；
推荐两个轻量方案：
- 用
conventional-changelog-cli（Node.js）：配置conventional-changelog-config-spec后，执行npx conventional-changelog -p angular -i changelog.html -s，它会按 commit message 规范（如feat:、fix:）自动归类并追加到文件 - 用 Python 脚本调
git log --pretty=format:"%h %s" --no-merges v1.0.0..HEAD，再按行匹配正则提取版本边界和变更类型——适合已有定制 commit 模板但不想引入 Node 生态的团队
注意：changelog.html 是产物，不是源码。它应该被 .gitignore 排除，或只保留最新一次生成结果；否则多人同时提交容易冲突。
为什么直接写 <pre><code> 显示 commit 日志很糟糕
有人把 git log --oneline 输出直接塞进 <pre><code>，看起来“有历史”，实际几乎不可用。
问题很明显：
- 没有语义分组：所有提交混在一起，看不出哪个属于
v2.3.0，哪个是临时调试提交 - 缺少上下文：
abc1234 fix login timeout不告诉你影响范围、是否向后兼容、要不要改配置 - 无法链接：commit hash 是死文本，点不了，也搜不到对应 PR 链接
- 格式污染：日志里可能含 ANSI 转义符或换行异常，在 HTML 里显示错位
真正的 Changelog 不是日志 dump，是面向用户/协作者的发布说明。哪怕只有三行，也要回答：这次升级我需不需要改代码？有没有破坏性变更？哪里能看详情？
部署时怎么避免 changelog.html 缓存导致用户看不到更新
浏览器对 HTML 文件缓存策略较激进，尤其当服务器没配 Cache-Control 时，用户可能一直看到旧版日志。
最简单有效的解法是：在 HTML 文件末尾加一行带哈希的注释，比如 <!-- build: 2a7f1e9 -->，然后每次生成时更新这个值（可用 git rev-parse --short HEAD）。再配合 Nginx 配置 expires 1h;，既减少重复请求，又保证一小时内能刷出新内容。
另一个常见错误是把 changelog.html 放在 CDN 缓存层级过深的位置，且没设 Cache-Control: no-cache, must-revalidate。如果 CDN 不支持基于 query 参数缓存（如 changelog.html?v=2.4.0），就别用参数骗缓存——直接改文件名更可靠，比如生成为 changelog-v2.4.0.html 并在首页用 link 标签指向它。
真正难的不是生成页面，而是让每次发布的意图准确传递出去。版本号、变更类型、影响说明、链接锚点，这四样缺一不可。漏掉一个，下游排查问题的时间就多花十分钟。
