建立 Webflow 頁面是做什麼的？

概覽

Webflow MCP 寫入工具會回報成功，但實際操作可能與你的要求不同。類別名稱會被重新命名、圖片未綁定任何資料、樣式套用到錯誤的斷點。每一次寫入都必須進行讀取回查。

核心原則：成功回應並非證據，元素樹才是。

如需處理 CMS 項目、部落格文章或頁面 SEO，請改用 CMS 專注的發佈技能。本技能專注於 Designer 表面：元素、樣式、資產、自訂程式碼。

鐵律

未經目前對話中明確批准，絕不可發佈到生產環境。

網站發佈會將 Designer 中每個頁面的所有暫存變更（包含你未做的改動以及仍可在生產環境存取的未列出頁面）一併送出。「我之前已經叫你發佈了」這句話在任務之間不適用。每次都要重新詢問。

暫存環境則不同，這是供審查工作的正常步驟。僅發佈到暫存子網域（空的「自訂網域」清單）是修復後的正常流程，接著在暫存環境進行 QA。僅發佈到主要生產網域，且僅在獲得批准後才能進行。

九大陷阱

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` 會替換整個區塊

頁面 head 與 footer 的自訂程式碼位於 data_scripts_tool，而非頁面或樣式工具：使用 get_page_freeform_code 與 set_page_freeform_code，並指定 location: "head"。

寫入是全有或全無，無法附加。務必先 get 目前的區塊，修改字串後，再完整 set 回去。寫入片段會靜默刪除 head 中其他所有內容。某些方案下，該工具也會拒絕 <script> 標籤，因此腳本應放入內嵌元素中（見下方說明）。

8. 透過 API 建立的頁面不會繼承你的基本 CSS

如果網站透過基本 CSS 元件設定根字型大小（例如 html{font-size:.625rem} 使 1rem 等於 10px），則透過 API 建立的頁面不會獲得該元件。在 Designer 中及發佈後，所有內容都會放大 1.6 倍。每個新頁面上的第一個元素都應是基本 CSS 元件。請在設定任何樣式之前檢查它。

9. 資產建立輸出會消失，且綁定會遇到速率限制

低於一定大小的 create_asset 輸出不會被保留，因此 22 個資產的批次會內嵌列印，必須立即抄錄。set_image_asset 每次執行一次讀取與一次寫入：每分鐘約十個綁定後就會遇到 429 錯誤。請以每批十個、間隔一分鐘的方式進行綁定，並維護一個包含名稱、資產 ID、日期與簽章列的表格。

自訂程式碼與腳本

某些帳戶會封鎖頁面腳本 API。若要在頁面上執行 JavaScript：

使用 register_inline_script（最多 2000 個字元）或 register_hosted_script
在頁面上的 HtmlEmbed 元素（透過 data_element_settings_tool 編輯，鍵值為 code）的 <script src> 中引用回傳的代管 URL

將頁面結構設計為每個區段一個內嵌元素，再加上一個載入器內嵌元素，負責引入動畫庫與你的腳本。使用版本化顯示名稱（如 sections.v17）而非修改已註冊的腳本：update_registered_script 對內嵌腳本會失敗，而版本化名稱只需編輯內嵌元素中的一個 URL 即可回滾。頁面 CSS 也以同樣方式代管，並使用版本號。

預覽草稿

草稿頁面無法透過 API 切換為已發佈狀態，且頁面分支出是 Enterprise 功能。因此，QA 草稿時應針對本機副本進行：包含即時導覽列與頁尾標記、網站 CSS、基本 CSS 規則以及來自 CDN 的動畫庫。

在隱藏分頁或無頭面板中，動畫時鐘會暫停。請強制執行：

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

隱藏面板的螢幕截圖在折頁以下會顯示為空白。請移動 body 以將某個區段帶入視圖進行截圖，並在實際 scrollTo 之後呼叫 ScrollTrigger.update()。

資產

三個步驟，而第三步正是大家經常遺漏的：

使用 create_asset 搭配檔案名稱與原始位元組的 MD5（32 位小寫十六進位）
以 multipart/form-data 格式將位元組 POST 到回傳的 uploadUrl，附加所有 uploadDetails 欄位以及 file 下的檔案。預期回應為 201。
使用相同名稱與雜湊值再次呼叫 create_asset 以完成上傳。

CDN URL 格式為 https://cdn.prod.website-files.com/<siteId>/<assetId>_<filename>。請參閱 asset-upload.md 取得可用的 curl 範例。

影片透過相同表單上傳（video/mp4、video/webm），並從一個內嵌元素中引用，該內嵌元素包含 autoplay muted loop playsinline 與一個預覽圖片。首頁影片會消耗大量頻寬，因此請提供較小的循環檔案與輕量版本給手機用戶。

速率限制

讀取操作（query_elements、get_all_elements、get_settings）會消耗資產與集合端點的配額，並在大量資產工作後開始回傳 429。寫入操作則不受影響。當 query_elements 遇到 429 時，get_all_elements（深度 2）通常仍可成功。

批次讀取：一次 query_elements 呼叫可以包含多個查詢。

驗證清單

每次建置工作階段後執行以下檢查，並回報結果，而非你的意圖。

使用 query_elements 依樣式名稱查詢你引入的每個類別；實際名稱必須與你的 CSS 與腳本目標一致
每個插入的圖片在其設定中都有 assetId
斷點樣式在你預期的斷點上讀取回查成功
head/footer 區塊仍包含你編輯前的所有內容
內嵌元素中註冊腳本的 URL 與你剛註冊的版本相符
資產 CDN URL 回傳 200，且內容類型與大小符合預期
基本 CSS 元件是頁面上的第一個元素
暫存頁面與你建置的內容一致：請取得暫存 HTML 進行檢查，不要僅憑假設

紅旗警示

「工具回傳成功，所以類別已套用」
「我先寫 CSS，稍後再檢查類別名稱」
「這是個小改動，我直接寫入 head 區塊」
「使用者已在這個專案中批准發佈」
「我發佈到所有網域以保持一致」

以上情況都代表：請先讀取元素樹，再繼續進行後續操作。

建立 Webflow 頁面