/website-build - 正确构建网站
源自为一个移动应用公司实际构建、翻译成五种语言、启动并加固真实营销网站的实践经验。参考文件中的每条规则都源于实际出错或耗费时间的事件。本文件是路线图，参考文件提供详细内容。
| 打开此文件 | 当你准备……时 |
|---|---|
references/01-architecture-pipeline-deploy.md | 设置文件夹和构建链、选择库、添加构建步骤、部署、配置托管/CSP/重定向、设置备份 |
references/02-design-typography-mockups.md | 定义令牌和字体、处理字体和换行、制作手机模型、放置图标/Logo、构建组件和动效 |
references/03-i18n-seo-geo.md | 翻译、新增市场、编写元数据/JSON-LD、站点地图/robots/llms.txt、实施GEO、优化性能、设置分析 |
references/04-qa-devices-modes.md | 测试任何内容：测试框架、设备/宽度/模式矩阵、应用内浏览器、无障碍、用户同意流程、对抗性测试和实时QA |
references/05-process-content-legal-launch.md | 运行项目：角色、审批、反馈循环、信息架构、事实、法律页面、用户同意、上线 |
scripts/qa/ | 运行QA框架（原始CDP，无需安装）以及WebKit/应用内浏览器矩阵（Playwright） |
scripts/backup/snapshot.py | 在编辑前对文件进行版本控制、列出版本、恢复；或将其安装为PreToolUse钩子 |
1. 阶段（按顺序）
- Brief (
05)：目标与行动号召、市场/语言、页面列表、带来源的事实表格、品牌资产、每个市场的法律实体、跟踪与用户同意、托管，以及负责合并生产环境的人员。 - Skeleton (
01)：一个源文件夹，主语言手动编辑，通过幂等标记块注入共享的页面框架，其他所有内容由构建器生成，_dist（优化后）和_deploy（托管）作为单向生成的副本，构建锁，从第一个文件开始使用git。 - Design system (
02)：每个背景的令牌，使用带rem和较小vw斜率的clamp()，图片带有真实的width/height，绝对路径的srcset，自托管子集字体（覆盖所有变音符号），每个元素一种动效系统，支持减少动效和无JavaScript模式。 - Imagery (
02)：从设计工具中按市场导出的真实产品截图（3x PNG → WebP）。切勿在光栅图像上叠加文字。在文件中修正Logo，而非使用混合模式。 - Copy and facts (
05)：一个事实列表，一个概念对应一个术语，每个市场的法律实体，根据受众选择正式/非正式语气。 - i18n (
03)：字典加精确文本匹配的构建器，运行时排版，hreflang（+ x-default），按市场的数据表，语言QA。 - SEO (
03)：标记之间的幂等后处理器，每个页面一个JSON-LD@graph，带真实最后修改时间的站点地图，robots（允许AI爬虫），一个真实的404页面。 - GEO (
03)：llms.txt（+完整版），facts.json，站点内外一致的实体数据，在无JavaScript提取下仍能保留的文本，然后是GEO测试协议，包括询问真实AI引擎。 - Performance (
03)：内联资源 → 哈希文件，WebP，首屏以下懒加载，自托管库，延迟加载标签管理器，在移动端和桌面端运行Lighthouse。 - Consent, analytics, legal (
03,05)：用户同意栏，Consent Mode v2（有意决定使用基本版还是高级版），仅在用户同意后加载标签，隐私政策中列出所有跟踪器，必需的 legal 页面，CSP 先以 Report-Only 模式运行。 - QA (
04)：完整的页面x宽度矩阵，各种模式，WebKit 和社交应用内浏览器，键盘/焦点测试，用户同意场景，链接/锚点/语言切换，对抗性审查，然后使用真机测试。 - Go-live (
05,01)：备份旧网站和DNS，重定向所有旧URL（保持商店列表路径精确无误），预览版与基线对比测试，切换，运行上线检查清单。
2. 硬性规则
- 绝不手动编辑生成的文件（语言版本、
_dist、_deploy）。编辑源文件或构建器，然后重新构建。 - 绝不手动在翻译构建器通过精确文本匹配的文案中插入
/<br>。换行在运行时完成。 - 一次会话构建并发布。构建锁会检查其所有者；如果被占用则等待，绝不要删除它。在完整构建前检查可用内存。
- 页面能渲染不证明任何问题：对每个内联脚本进行语法检查，扫描控制字符，运行整个矩阵测试。
- 每一轮反馈都应在构建中成为一个幂等检查步骤，如果目标文本消失，该步骤应失败。
- 生产环境由项目拥有者合并。托管、CSP、用户同意、跟踪和法律变更应先在侧分支上提交给技术审查员。
- 事实存在于一个列表中。两个页面上不同的数字是一个信任错误，也是一个GEO错误。
- 备份： 每个站点使用git，在每个阶段进行提交；对于提交之间的所有更改，使用
scripts/backup/snapshot.py（或其钩子）；上线前备份旧站点和DNS。 - 在构建、压缩后的输出上重新测试覆盖层、粘性栏和菜单。压缩工具可能会降低选择器的特异性。
- 在您的广告投放所使用的应用内浏览器中，以及在携带状态的页面（URL中包含令牌）上，测试CSP和用户同意。
3. QA 一句话总结
路径相对于此技能文件夹。首先运行 node scripts/qa/jscheck.mjs site/_dist，然后使用 QA_WIDTHS=1440x900,1280x800,1024x768,768x1024,430x932,390x844,360x780,320x700 运行 node scripts/qa/audit.mjs <folder-or-url>，接着运行 anchors.mjs、modes.mjs、console-sweep.mjs、shots.mjs（请自行查看截图），以及用于WebKit和Instagram/Facebook/TikTok应用内浏览器的 inapp.mjs。每个脚本遵循统一的退出代码约定：0 表示干净，1 表示发现问题（包括页面加载失败），2 表示用法错误，3 表示无法运行（缺少Chrome、axe-core或Playwright）。检查清单：04，章节“发布前”和“部署后”。