端到端构建 WordPress 网站
此方法存在的原因
代理在其反馈循环缓慢时设计得很糟糕。在 WordPress 内部布置页面，每次迭代需要三到五分钟——编写、保存、序列化、清除、重新加载、查看。在带开发服务器的本地 HTML 中，同样的循环只需五秒，设计质量比任何美学指令都更可靠地取决于迭代次数。
第二部分是交付约束：客户无需编写代码即可编辑网站。这禁止使用原始 HTML 块和模板拥有的内容——它约束的是转换过程，而从不约束绘制过程。
一句话总结：设计存在于文件中，而非页面内容中。WordPress 接收的是一个完成后的主题，而不是布局指令。
首先要遵循的两条规则
规则 0 —— 绘制阶段 2 时，假设阶段 4 不存在。 没有任何转换约束进入原型。在绘制时预先考虑“无 core/html”会悄悄移除深度、重叠和中心物体；结果虽然转换完美，但无人满意。
规则 0′ —— 不允许任何美学自由偏离参考。 有参考时，模型会偏向其自身的风格：参考是冷白色，它变成暖米色；参考用一种无衬线字体，它换成装饰性衬线；参考没有强调色，它给你加上一种。从参考中读取并复现七个注册不变量；更改其中任何一个都是需要向客户提出的问题，且需在编码前提出。这些不变量、注册关卡和测量脚本位于 references/register.md。
十条规则
每一条都源于一个实际犯过的错误。
- 必须有视觉参考。没有参考，输出将退化为统计中心：中性字体、紫色渐变、白色页面。
- 原型中必须使用真实照片。灰色方块会被视为损坏的图片。
- 在获得客户两次批准之前，任何内容都不能进入 WordPress 生产环境：即原型和部署计划。
- 主页是一个页面，而不是模板——
front-page.html包含页眉、post-content和页脚。 - 零个
core/html块。使用组、标题、段落和图片进行编辑。 - 图片位于媒体库中，每个
core/image都带有一个id。 - 所有交互变体都存在于页面中；脚本通过切换一个类来实现。
- 设计之下不使用第三方主题。
- 在编辑器内验收，而不是在前端——一个页面可以渲染完美，但在 Gutenberg 中无法使用。
- 像素级保真度通过测量而非肉眼判断：逐个选择器比较计算样式和几何尺寸。
阶段及其关卡
在前一个关卡未通过之前，不要开始下一个阶段。
| 阶段 | 负责人 | 退出标准 |
|---|---|---|
| 0 · 工作区 | 代理 | 项目位于用户工作文件夹，写入权限已验证 |
| 1 · 简报 | 客户 | 参考调查，从参考中提取的调色板和字体，“我要添加的内容”列表 |
| 2 · 原型 | 迭代 | 主页 HTML，通过注册关卡，客户批准 |
| 3 · 页面集 | 代理 | 每个页面都从同一个页眉/页脚源文件组装而成 |
| 4 · 块主题 + 暂存 | 代理 | 主题已构建；通过可重放工具设置本地 WordPress；暂存环境下通过关卡 1–5 |
| 5 · 部署 | 代理，计划经客户批准后 | 在 Web 根目录外备份，然后在生产环境运行相同工具 |
| 6 · 验收 | 代理 | 生产环境通过关卡 1–5，否则返回阶段 4 |
阶段 0–3 和部署计划：references/phases.md。HTML 到块转换：references/block-conversion.md。包含代码的五个关卡：references/acceptance.md。
暂存是本地化的，每次更改都是一个工具。 内容和配置由幂等 PHP 脚本（tools/install-site.php、tools/configure-*.php）编写，通过 PHP CLI 在本地副本上运行，而绝不在 wp-admin 中手动输入。相同的脚本在部署时会在生产环境重放，重复运行一次脚本不会改变任何内容——这是经过检查的，而非假设。
选择分支
每种网站的方法相同；不同之处在于阶段 4 及之后。
| 网站类型 | 变化内容 | 阅读文档 |
|---|---|---|
| 展示型 | 页面、表单（Contact Form 7 + Flamingo）、法律页面 | 本文件和阶段文档 |
| 商店 | WooCommerce 块模板、目录导入、产品筛选器、购物车/结账块、同意、支付、新闻通讯、订单确认 | references/store.md |
| Web 应用 | 自定义文章类型、角色、REST、动态块、账户流程——原型仍然驱动每个公开屏幕 | references/web-app.md |
references/store.md 基于实际构建进行测量（WooCommerce 11.2.2，块结账，块主题）。references/web-app.md 则不然：文档中会明确说明，并引导至相关的技能。
事实属于客户
原型可根据简报编造文案，但绝不可编造事实。评论、评分、客户数量、媒体标识、配送时间、服务价格、法律条款和公司身份等，应保留为可见的占位符——à compléter 用于只有客户才能提供的内容，à vérifier 用于从旧网站读取且可能已过时的信息。一个捏造的评论可能会通过所有关卡，却是可能让客户承担法律责任的唯一缺陷。
在评论、提交消息和报告中，说明哪些声明是测量所得（附带日期），哪些是读取所得（附带来源）。
工具
| 文件 | 使用时机 |
|---|---|
scripts/serve.mjs | 阶段 2——零依赖静态服务器，端口被占用时尝试下一个端口 |
scripts/assemble.mjs | 阶段 3——从一个 <head>、页眉和页脚源文件构建所有页面 |
scripts/fetch-fonts.mjs | 阶段 4——自托管 Google Fonts：访客无需向 Google 发起请求，无需根据 GDPR 声明 |
scripts/novamira.mjs | 阶段 5——通过 HTTP 调用 Novamira 能力，无需注册 MCP 服务器 |
assets/theme-skeleton/ | 阶段 4——最小块主题：带 blockGap: 0px 的 theme.json、editor.css、编辑器中的字体 |
参考文档
| 文件 | 阅读时机 |
|---|---|
references/register.md | 阶段 1 之前，以及展示任何原型之前 |
references/phases.md | 阶段 0–3，然后是阶段 5 的部署顺序 |
references/block-conversion.md | 阶段 4 期间，每次都读 |
references/acceptance.md | 阶段 4 和 6——五个关卡和测量规范 |
references/store.md | 任何 WooCommerce 网站 |
references/web-app.md | 会员、预订、仪表盘、任何有登录用户执行工作的场景 |
references/pitfalls.md | 当某个症状让你感到意外时立即阅读 |
相关技能：wp-theme-block-fse 用于 theme.json 和模板，wp-design-system 用于设计令牌，wp-woocommerce 用于钩子和 HPOS，wp-deploy 用于迁移，wp-plugin-architecture 和 wp-blocks-gutenberg 用于应用程序代码，wp-accessibility 和 wp-performance 用于验收前检查。