Cloudflare Pages 上的原生静态网站
无需构建步骤。编辑文件 → 推送到 main → Cloudflare Pages 自动部署。快速、廉价，且无需与工具链纠缠。
为什么选择原生（决策理由）
- 零构建/CI 开销；修复两行代码只需 30 秒部署。
- 无框架锁定或重构税。原则是“添加，而非重写”。
- 整个站点可搜索、可调试、清晰明了。
- 妥协之处：需要更多手动 DOM 代码。但在中小规模场景下值得。
仓库 + 部署
- 一个 GitHub 仓库 → Cloudflare Pages 项目，推送至
main分支时自动部署。 - Pages 提供仓库根目录内容。美化 URL：
/mi-cuenta.html在/mi-cuenta路径下访问。 - 函数（无服务器）位于
/functions目录（参见supabase-backend）。
部署仪式（每次部署都要执行）
- 编辑文件。
- 验证 JS 编译——绝不要推送损坏的内联 JS。提取内联
<script>块并对每个块运行vm.compileFunction；对于.js/.cjs文件使用node --check。参见reference/verify-inline.cjs。 - 缓存清除资源：
node .claude/cache-bust.cjs—— 在 HTML 中每个assets/**/*.css|js引用后添加?v=<git-short-hash>，并写入version.json。参见reference/cache-bust.cjs。 - 升级版本戳（单一来源，位于一个 JS 文件中，在页脚中低调显示）并记录日志。版本管理方案参见
project-continuity。 - 提交（使用项目语言，描述性提交信息）并包含合著作者声明，推送至
main。 - 验证上线：
curl已部署的资源，确认新的版本戳以及version.json与资源?v=参数匹配（它们必须一致，否则自动重载会陷入循环）。Cloudflare 机器人保护会阻止普通爬虫 → 使用浏览器 User-Agent。
.claude/通常被 gitignore，因此缓存清除/验证脚本保留在本地（它们在构建时在你的机器上运行，而非在仓库中）。
缓存清除 + 自动重载（消除“no se ve”电话游戏）
两层机制，均在 reference/ 中：
cache-bust.cjs—— 每次部署时重新在所有资源引用后添加?v=<git hash>，使浏览器重新获取变更的 CSS/JS，同时写入version.json = {"v":"<hash>"}。- 自动重载器（
reference/auto-reload.js）—— 一个微型脚本，包含在每个页面中，读取自身加载时的?v=，轮询/version.json（以no-store模式提供），当检测到新部署时：在标签页返回时重载（安全时机），在用户正在浏览时显示一次点击“Actualizar”横幅，并且绝不中断正在进行的输入（通过window.__noAutoReload选择退出，适用于考试/结账流程）。引导注意： 首次使用时，用户需硬刷新一次以加载重载器；之后自动生效。
通过 _headers 提供新鲜标记：
/version.json
Cache-Control: no-store, max-age=0
安全头部（仓库根目录下的 _headers）
始终设置：Content-Security-Policy（将 script-src/frame-src/connect-src 锁定到确切的 CDN 加上你的 Supabase URL 加上 wss 用于实时通信）、X-Frame-Options: DENY、X-Content-Type-Options: nosniff、Referrer-Policy: strict-origin-when-cross-origin、Permissions-Policy、Strict-Transport-Security。已遇到的陷阱：嵌入视频 iframe 时，需要在 frame-src 中添加播放器域名，否则浏览器会静默阻止。
可复用 CSS 约定
- 基于 CSS 变量的令牌主题系统；通过
data-theme="dark"重新映射和共享的localStorage键实现主题在页面/标签间同步。 - 深色模式：仅通过颜色对比是不够的——你还需要可见的层级结构（背景 < 表面 < 卡片），使用浅色步进和阴影，否则会显得平淡。
- 切勿硬编码
white/颜色；使用令牌，使主题能够响应。 - 不破坏全局的
.btn/.btn-primary；在作用域内覆盖。
本技能包含的文件
reference/cache-bust.cjs—— 资源标记 + version.json 写入器。reference/auto-reload.js—— 部署自动重载器（放入全局加载的 JS 文件中）。reference/verify-inline.cjs—— 部署前编译检查内联<script>块。reference/headers-example—— 初始_headers配置示例。