brandvm/webflow-audit

Webflow 审计：以小型验证步骤安全改动在线站点

一个在线站点包含访客、排名以及其他人的未发布内容。这里的每一项改动都不是从零构建：每次变更都起始于一次测量，单独发布，且可随时撤销。

共享规则同样适用（webflow-build › rules.md：未经明确确认不进行 commit、push、release 或 DNS 更改；聊天中不暴露凭据；以 Designer 优先；脚本存储在 repo 中）。其检查脚本（pnpm wf:*）负责测量；在 webflow-build.config.json 中将 stagingUrl 指向 staging 域名，并使用 --live 参数获取访客所见内容。

标签：[Claude] Claude 执行 · [Claude 检查] Claude 验证并报告 · [人工] 由人工执行；Claude 可跟踪但不可声称执行。

以下两条规则高于所有其他规则：

• 发布是站点范围的。 发布会将站点上所有待处理内容（包括他人未完成的编辑）一并推送出去。切勿将内容发布到线上域名，直到人工为该批次输入了单词 publish。每个“publish”仅覆盖一个批次，绝不涉及下一个批次。
• 先读后写。 审计过程不会向 Webflow 写入任何内容。

文档

repo 的 docs/handoff/ 目录下，随工作进展保持最新：

文件	内容
AUDIT.md	审计报告：测量内容及其数值和日期
STATUS.md	跟踪器：每项请求以客户自身措辞列出，并标注状态
DECISIONS.md	每项决策：谁做出、何时做出及其含义
ROLLBACK.md	回滚点，以及所有自定义代码的逐字记录（备份当时状态）
MANUAL-TODO.md	仅能在 Designer 中由人工执行的步骤

1. 只读审计

此步骤不向 Webflow 写入任何内容。按以下顺序执行：前两项最容易被忽略且无法事后补充，因为它们描述了站点在改动之前的状态。

• [Claude] 视觉基线（含噪声地板）。 在四个宽度下对每个关键页面执行 pnpm wf:baseline save --live，然后立即在不做任何改动的情况下执行 compare。两次未改动运行之间的差异（视频帧、轮播、延迟加载图片）即为噪声地板；按页面记录下来。将基线图片保留在 git 版本控制之外（文件较大）：.webflow-build/ 目录因此被忽略。
• [Claude] 标题大纲 对每个关键页面执行（pnpm wf:outline --live），结果保存在 AUDIT.md 中。
• [Claude] 速度： pnpm wf:perf --live，分别测试移动端和桌面端，对每个关键页面（不限于首页）执行 5 次运行取中位数及其范围。
• [Claude] 可访问性： pnpm wf:a11y --live --all-widths。
• [Claude] 链接与重定向： pnpm wf:links --live --external；站点设置中的重定向列表（导出为 CSV）；站点地图。结合 Search Console 报告为未找到的 URL，执行 pnpm wf:redirects test --live --file <export>：检查哪些旧 URL 返回 404、陷入循环、形成链式或跳转到首页。
• [Claude] 已发布 HTML： pnpm wf:html --live（检查默认字段名、代替按钮使用的链接、未在任何样式表中定义的类）。
• [Claude] SEO 与 schema： pnpm wf:seo --live --canonical：按页面检查标题、描述、规范链接、Open Graph 图片、索引状态以及任何 JSON-LD（能否解析；CMS 字段中的引号是否会破坏它）；全站范围内检查重复标题和描述、404 页面、robots.txt。标题大纲与 webflow-launch › headings.md 对比。
• [Claude] 跟踪脚本： pnpm wf:tracking --live：哪些标签在哪些页面加载、页面浏览是否被重复计数、Cookie 选择前和选择“拒绝”后运行什么、通过重定向传递的 gclid 和 UTM 参数。数据请求会被阻止，因此审计不会向客户账户发送任何数据。
• [Claude] 域名： pnpm wf:domain：证书、域名续订日期、注册商和 DNS 主机、http 和 www 重定向。
• [Claude] 库存清单，通过连接器读取：页面和文件夹；CMS 集合（含字段类型和条目数）；组件；字体及其加载方式；每一段自定义代码（站点 head 和 footer、每个页面的代码、每个 Embed）以及每个第三方脚本，并说明各自用途（wf:tracking 会列出页面加载的服务）；交互及其依赖页面；表单及其提交地址。
• [Claude] 报告 生成至 AUDIT.md：以简短条目和数字呈现发现，每条标注为“测量值”或“从代码读取”，按“可能带来的收益”和“可能造成的破坏”排序。任何未经测量的声明均须注明。门控条件： 人工审核报告。

2. 第一天状态跟踪

• [Claude] 根据需求简报 以及客户自己的检查清单（使用客户自身的措辞） 编写 STATUS.md，每项请求占一行：请求内容、状态（未开始、进行中、在 staging 上、已上线、已放弃及原因）、批次、日期。在较早的站点中，由于跟踪器创建较晚且措辞与客户列表不一致，导致请求丢失。
• [人工] 确认无遗漏。门控条件。
• [Claude] 后续每份报告都会更新跟踪器并给出统计数据：“14 项请求中 9 项已上线，2 项在 staging 上，3 项等待决策”。

3. 逐项决策

• [Claude] 一次提出一项决策，并用通俗语言说明其含义：对访客的影响、成本、可能出错的地方以及建议。
• [Claude] 决策做出后立即记录到 DECISIONS.md 中。
• 只有 面向客户的新内容（文案、图片、布局变更）才需要交由客户批准。底层技术决策（脚本加载方式、CSS 存放位置）由团队决定。

4. 回滚点（首次写入之前）

• [Claude] 在匹配当前线上内容的 commit 上打 git tag。
• [Claude] ROLLBACK.md 记录当前所有自定义代码的逐字副本：站点 head 和 footer 代码、每个页面的代码、每个 Embed。
• [人工] 创建 Webflow 备份（站点设置 › Backups），以日期命名；并在 repo 默认分支上启用分支保护。
• [Claude 检查] 回滚步骤已书面列出且每步均可执行：恢复代码块、将加载器指回旧版本、恢复备份。门控条件： 人工确认。

5. 对等发布（当底层代码结构发生变化时）

将站点迁移到模板时会改变代码的交付方式。该变更应单独首先发布，且 访客看不到任何变化。

• [Claude] 按现有行为原样移植。此步骤不进行重写或改进：这些属于后续批次，且每个批次都需要测量。
• [Claude 检查] 在四个宽度下对每个关键页面进行对等性检查：计算样式和几何形状与基线对比（pnpm wf:baseline compare，差异仅在噪声地板范围内）。
• [Claude 检查] 加载时间对等性（pnpm wf:film）：最终页面可能匹配，但第一秒内的加载过程有差异。需比较整体加载过程，而非仅最终状态。
• 然后像其他批次一样执行以下批处理步骤。

6. 批次处理，从最低风险开始

对工作进行排序，使得最安全、最确定的收益最先实施，并且每个批次可独立评估。一个批次 = 一个人能用一句话描述的变更。对每个批次：

1. 准备 在 repo 中（pnpm check && pnpm build && pnpm test）；说明 Webflow 中将发生什么变化以及访客会注意到什么。
2. 应用 到 Webflow（获得许可后）。然后提示：“重新加载 Designer”，并说明尚未发布的内容。
3. 仅发布到 staging。
4. 在 staging 上验证： 针对本批次的检查，加上受影响的页面的 baseline compare、html 和 console，覆盖四个宽度。
5. 询问还有哪些内容会一起上线。 [人工] 检查站点中其他待处理的变更（自己或同事的）。Claude 无法查看谁修改了什么；需如实说明并等待。
6. 人工输入“publish”。 然后发布到线上域名。
7. 使用 --live 验证生产环境： 与 staging 验证相同的检查，并重新测量本批次的指标（速度、错误、链接）。
8. 更新跟踪器 和客户检查清单；将结果记录到 AUDIT.md 中对应发现项的旁边。

• CMS 条目编辑（如修正拼写、新增条目）可直接上线：发布条目不会触发站点发布。页面和站点级别的变更始终执行上述八步。
• Webflow 对发布频率有限制：合理安排检查，使每个批次仅需一次 staging 发布和一次线上发布。

7. 仅保留实测改善项

• [Claude 检查] 前后对比均采用相同运行次数的中位数。落在该范围以内的差异视为噪声。
• [Claude] 如果一项变更未能改善其指标，或导致另一项指标恶化，则需撤销变更，并在跟踪器中注明原因。任何变更都不应因“本应改善”而保留。

8. 关闭

• [Claude] 前后对比报告：跟踪器中每项请求及其数值结果；哪些请求被放弃及原因；剩余工作。
• [Claude] 更新 ROLLBACK.md 至新状态；保留旧的 tag。
• [Claude] 将经验贡献给模板（webflow-build › rules.md › Contributing）。

小型任务（线上站点的一次修复）

修复一个损坏的链接、一个停止工作的轮播、一个无法提交的表单。采用相同的谨慎态度，分五步：

1. 复现 问题，在线上站点上找到确切发生条件（页面、宽度、浏览器、操作步骤）。
2. 修复 问题，在最小的范围内进行。先阅读 GOTCHAS.md 和经验教训：该问题通常已有先例。
3. 回归测试，如果 repo 中有该区域的测试，确保问题不会悄然重现。
4. 部署到 staging，分别在桌面端和手机宽度上进行测试；执行 pnpm wf:html 并查看页面控制台。
5. 停止。 报告问题内容、修改内容以及验证方式，等待批准后再进行 push、tag 或 publish。保留之前的发布 tag，以便加载器可回指。线上发布仍然需要人工输入“publish”，且需先检查其他待处理内容。