🔧 阿川の電商水電行

Shopify 顧問、維護與客製化

💡

小任務 / 單次支援方案

單次處理 Shopify 修正／微調

⭐️

維護方案

每月 Shopify 技術支援 + 小修改 + 諮詢

🚀

專案建置

Shopify 功能導入、培訓 + 分階段交付

👉 瞭解詳情 / 免費諮詢

小編精選 - 技術文章翻譯 · 02月17日

實際上，靜態 WordPress 不再是敵人

這是GitHub Copilot CLI 挑戰賽的參賽作品

這篇文章是為喜歡用 WordPress 寫作但又想要靜態網站（Hugo/GitHub Pages）的速度和安全性的開發者準備的。

我建造的

我花了數年時間來解決 WordPress 的效能和安全性問題。

優化緩存層、強化安裝、抑制插件臃腫——所有這些都是為了確保面向公眾的網站能夠正常運作。

後來我發現了靜態網站產生器。 Hugo。 Astro。快速、安全、優雅。

但幾個月來，我一直在調整主題、除錯建置管道，並與部署工作流程作鬥爭，這讓我明白了一個道理：我只是用一組問題換了另一組問題。

如今，我兩者都在使用。不是作為競爭對手，而是作為合作夥伴。

我一直遇到一個悖論： WordPress 可能是迄今為止最好的寫作環境。它的介面成熟，編輯器好用，你可以專注於真正重要的事情——寫作。

靜態網站產生器可能是迄今為止最佳的部署目標。它們速度快、安全、託管成本低，並且預設即可擴展。

那我們為什麼還要在它們之間做選擇呢？

在我之前的一篇文章的評論中，@juliecodestack 完美地捕捉到了這種矛盾：

“我花了很多時間調整 Hugo 網站而不是寫作，恐怕如果我轉到 Astro，也會做同樣的事情。”

這才是真正的問題。不是 WordPress，也不是 Hugo。而是編寫程式碼和部署程式碼之間的摩擦。

WordPress 保持公開性的問題不在於編輯器，而是其他一切。

將完整的 WordPress 網站公開意味著需要良好的託管服務、對外掛程式的嚴重依賴（至少在安全性和 SEO 方面）以及認真的維護。

而且預設情況下，性能參差不齊，這還算是客氣的說法。

尋找替代方案

這項觀察逐漸促使我去尋找其他解決方案。

一段時間以來，我一直在將內容發佈轉移到靜態網站上。

但我真正想要的其實更簡單：保留 WordPress 作為寫作環境，同時完全消除其公共存在。

如今，靜態網站幾乎可以在任何基礎架構上快速部署，因此，只要擁有強大的部署解決方案，繼續使用 WordPress 作為前端並不總是那麼有意義。

正常寫作，自動發布。

無需手動匯出，無需執行腳本，操作簡單。

現有工具：有效但笨重

我的 WordPress 部落格上有數十篇文章，我開發了一套 Python 工具，可以將整個網站匯出到 Hugo 或 Astro。

功能齊全、可靠，但基於全球匯出邏輯：完整網站產生、轉換，然後部署。

流程有效，但很繁瑣。

在日常寫作過程中，這種做法尤其不自然。

為了尋求更流暢的編輯工作流程，這個專案應運而生。

解決方案：一個 WordPress 插件，可自動將已發布的文章同步到 GitHub 儲存庫，將其轉換為具有 Hugo 相容的前言的 Markdown，優化圖像（WebP/AVIF），並觸發 GitHub Actions 工作流程以部署靜態站點。

技術棧：

WordPress 6.9+ (PHP 8.1+)
GitHub API（透過 Trees API 實作原子提交）
操作調度器（非同步處理）
介入性影像（局部優化）
Hugo（靜態網站產生器）
GitHub Actions + GitHub Pages（部署）

主要特點：

✅ 完全非同步同步（無管理員阻塞）

✅ 原子提交（Markdown + 所有圖片合併在一個提交中）

✅ 僅支援原生 WordPress API（符合 WordPress.org 標準）

✅ 多格式影像最佳化（AVIF → WebP → 原始格式）

✅ 無需任何 shell 命令（100% 使用 GitHub API）

✅ HTTPS + 個人存取權令牌驗證

✅ 用於批次操作的 WP-CLI 指令

示範

工作流程現已投入運作。

您可以在這裡嘗試： WordPress 管理後台（登入名稱： tester ，密碼： Github~Challenge/2k26需具備作者權限）。您可以在網站程式碼倉庫中查看已提交的文件，也可以在.github/workflows下找到工作流程。

結果已在演示網站上顯示—如下所示：

{% embed https://pcescato.github.io/hugodemo/posts/2026-02-08-why-i-finally-stopped-fighting-my-publishing-workflow/ %}

文章仍然使用WordPress撰寫，與以前一樣。

發布或更新時，專用外掛程式會自動觸發與 GitHub 儲存庫的同步。

每條內容都轉換為 Markdown，並帶有 Hugo 特有的 front matter，以及優化的圖像（WebP 和 AVIF）。

所有內容都透過 GitHub API 以單一提交的方式發送。

接下來，GitHub Actions 工作流程接管：產生靜態站點，然後部署到 GitHub Pages。

具體來說，現在只需在 WordPress 上發佈網站，即可將網站的完整靜態版本上線，無需手動匯出或額外幹預。

現實世界的挑戰

這並非一次一帆風順的48小時衝刺。該專案經受住了許多現實考驗：

Hugo主題版本地獄：我想要的主題要求Hugo最低版本為0.146.0。我的本地安裝版本是0.139.0。 GitHub Actions預設版本為0.128.0。每個環境都需要明確地鎖定版本，除錯失敗意味著要在三個不同的建置環境中解碼晦澀難懂的TOML錯誤。

GitHub Pages URL 卡頓：部署後的網站最初渲染時內部連結失效，原因是 Hugo 的baseURL配置與 GitHub Pages 的預期不符。本地建置的頁面運作正常。 CI 建置部署後，相對路徑指向無效頁面。解決方案：在工作流程中硬編碼生產環境 URL，並接受本機預覽頁面導航略有不正常。

圖片處理管道記憶體限制：在共享主機上，每篇文章處理 10 張以上 AVIF 編碼的圖片會超出 PHP 的記憶體限制。第一次嘗試：出現致命錯誤。第二次嘗試：停用 AVIF，保留 WebP。最終解決方案：將memory_limit增加到 512M，並按順序批次處理圖片，而不是並行處理。

操作調度器競態條件：早期版本在快速多次儲存文章時會建立重複提交。 WordPress 的save_post鉤子會在自動儲存、手動儲存和快速編輯時觸發。需要：防抖邏輯、瞬態鎖和文章元資料標誌來防止冗餘同步。

PHP 8.1 嚴格模式：對null值呼叫一次explode()函數就足以凍結整個同步管道。我們必須實作try-catch-finally模式，以確保即使程式崩潰，同步鎖定也能被釋放，UI 也能及時更新。從此告別後台管理介面卡死的尷尬。

Git 換行符之爭（LF vs CRLF） ：GitHub Actions Linux 執行器會因為換行符號不符而拒絕在 Windows 上修改的檔案。解決方案：透過.gitattributes全域強制使用 LF。只需一個配置文件，即可解決跨平台相容性問題。

部分保存陷阱：WordPress 的標籤式介面只會提交可見欄位。更新 Front Matter 範本時，GitHub PAT 欄位未被提交，導致意外刪除。修正方法： array_merge()函數在部分更新時保留現有值。

這些都不在最初的規格說明中。但所有這些都是發貨的必要條件。

時間投資的現實

「48小時」的實際意義是：

|--------------------------------------------- | ------------------ | ---------------- | -------------------- |

| 外掛樣板程式碼 + WordPress 標準 | 約 4 小時 | 20 分鐘 | 3 小時 40 分鐘 |

| GitHub API 整合（樹、引用、提交） | 約 6 小時 | 1.5 小時 | 4 小時 30 分鐘 |

| 影像優化流程 | 約5小時 | 2小時 | 3小時 |

| 非同步佇列設定（操作調度器） | 約3小時 | 45分鐘 | 2小時15分鐘 |

| 管理員介面 + 設定頁面 | 約 4 小時 | 1 小時 | 3 小時 |

| Hugo 轉接器（Markdown + 前元資料） | 約 2 小時 | 30 分鐘 | 1 小時 30 分鐘 |

| 除錯實際問題 | 約 8 小時 | 約 8 小時 | 0 小時（此處無 AI 幫助） |

|總計|約32小時|約14小時|約18小時|

Copilot 加速了結構化實施。但它對架構決策、除錯特定環境故障或理解 WordPress.org 合規性要求沒有任何幫助。

為什麼本地影像優化很重要

該外掛程式會在 WordPress 伺服器上處理圖片，然後再上傳到 GitHub 。這一點至關重要：

不進行局部最佳化：

將 5MB 的原始 JPEG 檔案上傳到 GitHub
GitHub Actions 必須下載、處理（ImageMagick/Sharp），然後部署
組裝時間：每根柱子 2-3 分鐘
GitHub Actions 執行器耗時：高
建置失敗會在 Git 歷史記錄中留下孤立的大檔案。

採用局部最佳化（目前方法）：

WordPress 產生 AVIF (50-150KB) + WebP (100-300KB) + 原始文件
每篇貼文上傳給 GitHub 的總大小約為 500KB。
GitHub Actions 只會複製文件，不會進行任何處理。
建置時間：15-30秒
乾淨的 Git 歷史記錄，最少的執行器使用

權衡之下：PHP 記憶體限制和 WordPress 端的處理時間。但 WordPress 99% 的時間都處於空閒狀態。 GitHub Actions 執行器按分鐘收費。

本地處理會將瓶頸轉移到資源空閒的地方。

建築學

目前處理的內容：

✅文章和頁面：兩者均可自動同步，並包含正確的 Hugo 前元資料。

✅刪除：在 WordPress 中刪除文章/頁面會觸發 GitHub 中的檔案刪除操作。

✅更新：編輯內容會重新同步，覆蓋現有文件

✅類別和標籤：已轉換為 Hugo 分類法（位於 front matter 中）

✅特色圖片：已最佳化並在 front matter 中連結（ featured_image欄位）

✅自訂欄位：基本欄位對應到前端元資料（可透過適配器擴充）

目前限制（MVP 範圍）：

⚠️草稿處理：草稿保留在 WordPress 中，不會同步（有意為之）

⚠️版本控制：僅已發布版本同步，版本歷史記錄保留在本地。

⚠️複雜區塊：Gutenberg 區塊會轉換為 HTML，然後轉換為基本的 Markdown（不支援高級區塊保留）

⚠️短程式碼：轉換前會先渲染成 HTML（遺失原始短程式碼）

⚠️ ACF/元框：僅支援標準自訂欄位（ACF 需要自訂適配器擴充功能）

⚠️作者頁面：尚未實現（單一作者部落格功能正常）

審慎的權衡取捨：

WordPress 仍然是權威來源。該插件不支援雙向同步。如果您直接在 GitHub 中編輯 Markdown 文件，這些變更不會同步到 WordPress。這是有意為之——追求簡潔而非複雜。

主題變更與 SSG 遷移：

由於通用的前面板模板系統，現在更改 Hugo 主題甚至遷移到不同的靜態網站生成器 (SSG) 都變得非常簡單：

在插件設定中更新 front matter 模板（無需更改程式碼）
透過 WP-CLI批次重新同步所有文章（ wp jamstack sync --all ）
（如果目錄路徑已更改）可選地清理Git 中的舊檔案結構

適配器模式已經就緒。增加對 Jekyll、Eleventy 或 Astro 的支援意味著需要實作一個新的適配器類別——核心同步引擎保持不變。

目前尚未實現自動化的功能是：在內容結構截然不同的靜態網站（例如，Hugo 的content/posts/與 Astro 的src/content/blog/ ）之間進行遷移。這需要在 Git 中執行批次檔案移動操作，而目前該操作仍需手動完成。

但是，在同一個靜態站點產生器 (SSG) 中更改 front matter 的約定呢？這現在是設定更改，而不是重構專案。

該存儲庫包含：

WordPress外掛（符合WordPress.org標準）
GitHub API 整合（原子提交）
異步同步管理（操作調度器）
產生與 Hugo 相容的 Markdown 文件
用於部署的 GitHub Actions 工作流程

工作原理

詳細流程如下：

1. 寫作：標準的 WordPress 介面，寫作體驗沒有變化

WordPress 編輯器

2. 自動提交：GitHub 倉庫接收 Markdown 文件、優化後的圖片和 front matter。

GitHub提交

您可以看到.github/workflows資料夾，其中包含hugo.yml檔案 (1)、 content資料夾 (2)、 static/images夾 (3) 和上次部署狀態 (4)。

3. Hugo 結構： content/posts/結構自動生成，命名正確

4. 已部署網站：透過 GitHub Pages 在線上部署靜態版本，效能優異

靜態網站

整個流程構成了一個簡單的發布鏈：在 WordPress 中編寫內容，發布，然後讓剩下的事情自動執行。

倉庫： atomic-jamstack-connector

技術亮點

1. 通用前置資訊引擎

我們沒有為單一 Hugo 主題硬編碼插件，而是建立了一個原始模板系統。使用者可以定義自己的 YAML（或 TOML）文件，其中包含自訂分隔符號和占位符，例如{{id}} 、 {{title}}或{{image_avif}} 。

這意味著同一個插件可以適應任何 SSG 約定：

Hugo 附有 YAML 前置訊息
Jekyll 有不同的分類名稱
帶有自訂資料結構的 Eleventy

您可以控制輸出格式，插件只是填滿空白部分。

2. 透過 WordPress ID 進行資產管理

為了確保連結永不斷開，優化後的圖片（WebP 和 AVIF）儲存在以 WordPress ID 命名的資料夾中： static/images/1460/ 。

為了SEO，你把文章別名改了十次？你的圖片永遠不會失效。 ID是固定的。文件路徑是永久的。

3. 原生 WordPress 集成

該插件以一等公民的身份集成，擁有自己的側邊欄選單和選項卡式導航。

基於角色的安全機制：作者只能看到自己的同步歷史記錄。關鍵設定（GitHub PAT）僅限管理員存取。

負責任的清理：「徹底卸載」選項會在卸載時刪除所有插件痕跡（選項和帖子元資料），不會對資料庫造成任何污染。

4. 透過 GitHub Trees API 實現原子提交：

該插件不使用多個順序提交（每個映像一個提交，Markdown 檔案一個提交），而是使用 GitHub 的 Git 資料 API 建立一個包含所有檔案的單一提交：

// Collect all files (Markdown + images)
$all_files = [
    'content/posts/2026-02-07-this-is-a-post.md' => $markdown_content,
    'static/images/1447/featured.webp' => $webp_binary,
    'static/images/1447/featured.avif' => $avif_binary,
    'static/images/1447/wordpress-to-hugo-1024x587.webp' => $webp_binary,
    'static/images/1447/wordpress-to-hugo-1024x587.avif' => $avif_binary,
];

// Single atomic commit
$git_api->create_atomic_commit($all_files, "Publish: This is a Post");

這種方法是事務性的：要么所有操作都提交，要么所有操作都不提交。沒有部分狀態，歷史記錄更清晰。

5. 超越 Hugo：多 SSG 架構

雖然此演示針對的是 Hugo，但適配器模式並非僅限於單一 SSG。同一套程式碼庫可以支援：

Hugo（YAML/TOML 前置訊息，content/posts/）
Jekyll（不同的分類約定，_posts/）
Eleventy（自訂資料結構，src/content/）
Astro（內容集合，src/content/blog/）

新增的 SSG 意味著編寫一個適配器類別——同步引擎、映像優化和 GitHub 整合保持不變。

這種架構選擇將外掛程式從「僅限 Hugo」轉變為適用於任何靜態網站工作流程的平台。 4300 萬個 WordPress 網站不僅僅是 Hugo 的潛在用戶——它們都是靜態網站的潛在採用者，毋庸置疑。

6. WordPress原生相容性：

為了滿足 WordPress.org 的要求，該外掛完全使用 WordPress 原生 API：

wp_remote_post()而不是 curl
使用WP_Filesystem取代file_put_contents()
$wpdb準備的語句
不使用exec() 、 shell_exec()或 Git CLI

因此，它適合發佈到官方 WordPress 外掛程式庫。

我使用 GitHub Copilot CLI 的經驗

當我開始這個專案時，我並不是在尋找一款可以幫我寫程式的工具。

我當時正在尋找一種方法來加快一個架構已經很清晰的專案的執行速度。

我之前在其他專案中已經使用過 GitHub Copilot CLI、Gemini CLI 和各種 LLM，我知道這些工具可以快速產生程式碼。

但我知道，如果沒有一個精確的框架，他們主要產出的就是…程式碼。

未必是一個連貫的系統。

注意：這不是編輯器中的自動完成功能，而是能夠根據結構化提示產生完整檔案的命令列工具。

首先是規範，其次是程式碼

第一步不是編寫程式碼，而是編寫規範，明確專案範圍，並將專案分解成各個功能模組。

確定不可協商的限制條件：僅限 WordPress 原生功能，禁止 shell 執行，可靠的非同步處理，原子性的 GitHub 提交，符合 WordPress.org 規範，以便在官方儲存庫中發布插件並造福社群。

然後將開發過程組織成一系列階段。

這項工作與技術專案經理在將實施工作委託給團隊之前所做的工作非常相似。不同之處在於，這裡的「團隊」是由一個能夠快速產生程式碼的工具組成——前提是指令清晰明確。

所以，我並沒有按照傳統意義上的方式來寫程式。我寫的是功能和技術規格、提示資訊、完善的說明以及修正後的操作步驟。

每個步驟都包括描述需要建置的內容、驗證已生產的內容，然後進行調整。

有時 Copilot 第一次就能提出適當的結構。有時則需要修改、澄清和進一步限定。

工作模式

很快，一種工作模式就出現了：規範→生成→驗證→修正→迭代。

在這個過程中，Copilot 的行為與其說像是魔法生成器，不如說更像快速執行器。

它可以幾秒鐘內建構整個類，提出一個連貫的實作方案，或是重構一個完整的程式碼區塊。

但它也可能忘記重要的鉤子，覆蓋現有的方法，或產生不符合初始約束的功能程式碼。

實際問題案例：

方法被不完整的存根所取代
鉤子未註冊，導致靜默故障。
檔案已生成，但尚未實際寫入磁碟。
啟動時出現致命錯誤，這是嚴格 WordPress 環境的典型特徵。

每起事件都需要回歸基本原則：核實、理解、糾正、重新制定方案。

這究竟意味著什麼

這或許是整個體驗中最有趣的部分。

有效使用 Copilot 並不意味著編寫一個提示然後等待結果。

這更像是持續的試執行，指令的品質直接決定了最終產品的品質。

在這種情況下，該工具對於加速所有結構化操作都特別有效：類別建立、文件組織、重複函數實作、重構、文件編寫。

一旦目標明確，執行速度就能非常快。

但是，架構、技術選擇和整體連貫性的責任仍然完全在於人。

真實價值

最終，這種體驗與其說是“人工智慧輔助開發”，不如說是一種輔助技術指導。

程式碼產生速度很快，但必須經過深思熟慮、監督和持續驗證。

這個專案只花了不到兩天就完成了。這並不是因為這個工具取代了設計工作，而是因為一旦設計工作完成，執行速度就可以大幅加快。

GitHub Copilot CLI 最有趣的地方可能就在這裡：它不是開發的替代品，而是已經經過深思熟慮和結構化的專案的加速器。

審計追蹤優勢

除了編寫程式碼之外，GitHub Copilot CLI 還扮演技術記錄員的角色。

我的會話歷史記錄經歷了22 個不同的檢查點，記錄了從最初的基礎架構到最終安全加固的每一次架構轉變：

001-wordpress-plugin-foundation
002-media-processing-with-avif-support
003-deletion-and-bulk-sync
004-atomic-commits-and-monitoring
...
019-fix-plugin-check-errors
020-add-nonce-security
021-uninstall-api-compliance
022-fix-nonce-sanitization-warnings

在此瀏覽完整的檢查點歷史記錄： https://github.com/pcescato/atomic-jamstack-connector/tree/main/copilot-doc

每個檢查點都包含上下文文件，例如wordpress-api-compliance-guide.md 、 token-preservation-fix.md或settings-merge-test-plan.md 。

這不僅僅是一個副作用——它對可維護性來說是一個巨大的勝利。

它將人工智慧產生的「黑盒子」轉化為透明的、分步驟的工程日誌。六個月後，當我需要了解某個特定決策的緣由時，我不需要猜測。檢查點歷史記錄會揭示一切。

哪些方面做得好：

✅ 依照 WordPress 標準快速建立類

✅ 產生樣板程式碼（鉤子、過濾器、隨機數）

✅ 重構大型程式碼區塊（順序提交 → 原子提交）

✅ 從內嵌註解產生文件

需要持續監督的事項：

⚠️ 架構決策（適配器模式、非同步佇列）

⚠️ WordPress.org 合規驗證