构建 Webflow 页面是做什么的？

概述

Webflow MCP 写入工具报告操作成功时，实际上可能静默地执行了与你要求不同的操作。类名会被重命名，图片绑定到无效目标，样式会应用在错误的断点上。每次写入都必须通过读取来验证。

核心原则：成功响应不是证据。元素树才是。

对于 CMS 项目、博客文章和页面 SEO，请改用侧重于 CMS 的发布技能。本技能专注于 Designer 表面：元素、样式、资源、自定义代码。

铁律

未经当前对话明确批准，切勿发布到生产环境。

发布站点会将 Designer 中所有已暂存的更改推送到每个页面，包括你未做的工作以及尚未上线但仍在生产环境可访问的未发布页面。"我之前已经告诉过你发布了"这句话在不同任务之间不通用。必须再次请求。

暂存环境则不同，它是用于审查工作成果的。仅发布到暂存子域名（空的自定义域名列表）通常是修复后的标准步骤，随后在暂存环境中进行质量检查。仅发布到主生产域名，切勿发布到站点上的所有域名，并且必须经过批准。

九大陷阱

1. `whtml_builder` 会重命名冲突的类名

当你请求一个已存在的样式名称（例如 hp2-proof）时，你会得到 hp2-proof-1。请求 hp2-proof-n 时，你会得到 hp2-proof-n-1。链式冲突会产生 hp2-proof-link-1-2。包装的 div 常常完全没有类名。

不会报错。然后你的头部 CSS 定位到一个不存在的类，已注册脚本中的任何 querySelectorAll('.hp2-proof') 都会匹配到零个元素，因此滚动动画永远不会执行。

始终在插入后通过 query_elements 按样式查询元素，读取真实的 styleNames，并据此编写你的 CSS 和脚本选择器。没有类名的包装器可以通过 .parent-class > div 访问。

2. `html` 中的类仅在已存在时才会生效

html 参数中引用的类仅在以下两种情况下才会绑定：该样式已存在于站点中，或在同一个调用中的 css 参数中定义了它。否则，元素会以无类名状态插入，并且仍然报告成功。请在你的 css 中定义你使用的每个类。

该构建器也不支持后代选择器。请使用单类名和组合类名 (.a.b)。@media 和 clamp() 可以正常使用。

3. `whtml_builder` 需要一个单一的根元素

顶级有多个兄弟元素会导致插入失败或部分插入。请用一个容器包裹它们。

4. 作为标记插入的图片不会绑定

html 中的 <img> 会返回 partial_success，并提示“资产库中不存在”。请先插入元素，然后使用 set_image_asset 方法并传入资产 ID 来绑定它。

5. `update_style` 的作用域由 `breakpoint_id` 决定，而非 `breakpoint`

breakpoint 键会被静默忽略，样式会写入基础断点，覆盖桌面端设置。仅当按作用域写入成功时，响应中才会显示 breakpoints 键。请显式传递 breakpoint_id，并回读验证。

6. `set_style` 是替换，而非添加

set_style 会移除所有现有样式，并仅应用你传递的样式。要添加一个类，请先读取当前的 styleNames，然后传递完整的列表。

7. `set_page_freeform_code` 会替换整个代码块

页面头部和底部自定义代码保存在 data_scripts_tool 上，而非页面或样式工具中：使用 get_page_freeform_code 和 set_page_freeform_code，并指定 location: "head"。

写入是全量替换。没有追加操作。始终先 get 当前的代码块，修改字符串，然后完整地 set 回去。写入片段会静默删除头部中所有其他内容。此外，在某些计划中，它还会拒绝 <script> 标签，这就是为什么脚本要放在嵌入元素中（见下文）。

8. 通过 API 创建的页面不会继承你的基础 CSS

如果站点在基础 CSS 组件中设置了根字体大小（例如 html{font-size:.625rem}，这样 1rem 等于 10px），那么通过 API 创建的页面不会获得该组件。在 Designer 中和发布后，所有内容的渲染尺寸都会大 1.6 倍。每个新页面的第一个元素都应该是基础 CSS 组件。在设置任何样式之前检查它。

9. 资源创建的输出会消失，绑定操作有速率限制

小于某个尺寸的 create_asset 输出不会被持久化，因此一组 22 个资源会以内联方式打印，必须立即转录。set_image_asset 每次执行一次读取和一次写入：大约每分钟 10 次绑定后会收到 429 错误。请以每次 10 个为一组进行绑定，每组间隔一分钟，并维护一个包含名称、资源 ID、日期和签名行的表格。

自定义代码和脚本

某些账户上的页面脚本 API 被阻止。要在页面上运行 JavaScript，请执行以下操作：

register_inline_script（最多 2000 个字符）或 register_hosted_script
将返回的托管 URL 引用到页面上一个 HtmlEmbed 元素 内的 <script src> 中，通过 data_element_settings_tool 编辑，键为 code

将页面结构化为每个区块一个嵌入，再加上一个加载动画库然后加载脚本的加载器嵌入。对显示名称进行版本化（例如 sections.v17），而不是修改已注册的脚本：update_registered_script 对内联脚本会失败，而版本化的名称可以通过编辑嵌入中的一个 URL 来回滚。以同样的方式托管页面 CSS，并加入版本号。

预览草稿

草稿页面无法通过 API 切换到已发布状态，并且页面分支是 Enterprise 功能。因此，请对照本地副本对草稿进行 QA：实时导航和页脚标记、站点 CSS、基础 CSS 规则以及来自 CDN 的动画库。

在隐藏标签页或无头面板中，动画心跳会暂停。请强制执行：

gsap.ticker.lagSmoothing(0); gsap.ticker.tick();

隐藏面板的截图在折叠部分以下会呈现空白。移动 body 元素使某个区块进入视图以便截图，并在真正的 scrollTo 之后调用 ScrollTrigger.update()。

资源

三个步骤，第三步是人们经常遗漏的：

使用文件名和原始字节的 MD5 散列值（32 位小写十六进制）调用 create_asset
将字节以 multipart/form-data 形式 POST 到返回的 uploadUrl，附加所有 uploadDetails 字段以及 file 下的文件本身。期待 201 响应。
使用相同的名称和散列值再次调用 create_asset 以完成最终确认。

CDN URL 的格式为 https://cdn.prod.website-files.com/<siteId>/<assetId>_<filename>。有关可运行的 curl 脚本，请参阅 asset-upload.md。

视频通过相同的表单上传（video/mp4，video/webm），并在嵌入元素中引用，使用 autoplay muted loop playsinline 属性以及一个海报图。首页视频是带宽消耗大户，因此请为手机端提供小型循环视频和精简文件。

速率限制

读取操作（query_elements、get_all_elements、get_settings）会唤醒资源和集合端点，并且在大量资源操作后开始返回 429 错误。写入操作仍可正常工作。当 query_elements 返回 429 时，深度为 2 的 get_all_elements 通常仍能成功。

批量读取：一次 query_elements 调用可以包含多个查询。

验证检查清单

每次构建会话后运行此清单，并报告结果，而不是你的意图。

对于你引入的每个类，通过 query_elements 按样式名称进行查询；实际名称与你的 CSS 和脚本定位的目标一致
每个插入的图片在其设置中都具有 assetId
断点样式在你预期的断点下回读正确
头部/底部代码块仍然包含编辑前它拥有的所有内容
嵌入中的已注册脚本 URL 与你刚刚注册的版本匹配
资源 CDN URL 返回 200 状态码，并具有预期的内容类型和大小
基础 CSS 组件是页面上的第一个元素
暂存的页面与你构建的一致：获取暂存环境的 HTML 并检查，不要假设

危险信号

“工具返回了成功，所以类已经应用了”
“我现在写 CSS，稍后再检查类名”
“只是一个小改动，我直接写头部代码块吧”
“用户在本项目早期已经批准了发布”
“我将发布到所有域名，以便保持一致”

这些信号都意味着：在继续之前，回读元素树。

构建 Webflow 页面