BIGboss248/nextjs-wordpress

Next.js 開發環境設定（nextjs-dev-setup）

一個結構化的端到端編排操作手冊，用於探索、配置並驗證 Next.js App Router 開發環境、反向代理路由（Traefik / Nginx）以及位於 docs/project.json 的單一事實來源。

---

前置條件與探索

• 零中斷掃描：在提問之前，先掃描現有儲存庫檔案（package.json、鎖定檔、樣式表、docs/adr/*.md、docs/plan.md、CONTEXT.md）。
• 查閱 project-json-schema.md 以了解中繼資料結構與自動推斷規則。

---

階段 0：多輪設定訪談（Grilling）與計劃生成

以漸進式、適應性回合（每回合後等待使用者回應）的方式進行互動式訪談，以客製化設定：

1. 第一回合（範圍與工具）：探詢目標測試套件（Jest, Playwright, Storybook）、MCP 伺服器以及 @shadcn/lint 強制規則。
2. 第二回合（反向代理與生產環境託管）：探詢網域名稱、連接埠以及反向代理策略：
   • 透過 Docker Compose 使用的 Traefik：使用從環境變數（${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}）讀取的 Compose 標籤進行自動容器探索，並啟用抗緩衝。
   • 透過主機系統使用的 Nginx：在 /etc/nginx/sites-available/<domain> 中使用 Certbot SSL 憑證的獨立配置。
3. 第三回合（CI/CD、Git Hooks 與 Registry）：探詢 Husky pre-push 測試套件、Commitlint 以及 GitHub Actions Release Please / GHCR 工作流程。
4. 查閱 setup-interview-rounds.md 以取得完整的問題集與分支邏輯。
5. 計劃與執行：在套用變更前，生成並呈現一個 implementation_plan.md 成品，詳細說明所有計劃的檔案創建、配置和套件，然後直接開始執行，無需等待手動確認。

---

逐步執行流程

階段 1：專案中繼資料與開發者工具（docs/project.json）

1. 根據使用者訪談選擇，使用 project.template.json 初始化 docs/project.json。
2. 使用 vscode-launch.json.template 配置 .vscode/launch.json。
3. 使用 <ProgressBarProvider> 搭建 app/providers.tsx，使用 providers.tsx.template，並使用複合 <Link>，使用 Link.tsx.template。
4. 使用 env.example.template 搭建 .env.example 用於生產環境，使用 env.local.template 搭建 .env.local 用於本地開發。
5. 應用程式圖示、Apple 圖示與 PWA Manifest：將 manifest.ts.template 部署到 app/manifest.ts。在根目錄的 app/favicon.ico、app/icon.png 和 app/apple-icon.png（或動態 ImageResponse 圖示）中配置使用者提供的 favicon。查閱 app-icons-and-pwa-guide.md。

階段 2：測試套件（Jest, Playwright 與即時導航）

[!IMPORTANT] 無虛擬測試檔案（規則 3）： 請勿在工作區中創建佔位/範例測試檔案。僅配置框架檔案和腳本。範例模式可在 sample-component.test.tsx、sample-navigation.spec.ts 和 sample-component.stories.tsx 中找到。

1. Jest 單元測試：配置 jest.config.ts.template 和 jest.setup.ts.template。
2. Playwright E2E 與即時導航：安裝 @playwright/test 和 @next/playwright（pnpm add -D @playwright/test @next/playwright），配置 playwright.config.ts.template，並安裝瀏覽器。
3. Next.js 即時配置：在 next.config.ts 中配置 cacheComponents: true、partialPrefetching: true 和即時洞察。
4. Storybook 研討會：配置 .storybook/main.ts 和 .storybook/preview.tsx。
5. 查閱 testing-guide.md 和 storybook-guide.md 中的架構。

階段 3：雙 MCP 伺服器配置

[!IMPORTANT] Antigravity 全域 MCP 載入規則： AG 僅載入在主機系統（~/.gemini/antigravity/mcp_config.json 和 ~/.gemini/config/mcp_config.json）上全域配置的 MCP 伺服器。為確保可攜性，工作區 mcp.json 亦會維護。兩者都必須配置。

1. 配置 next-devtools、playwright、storybook 和 codebase-memory-mcp。
2. 防止口吃：透過 codebase-memory-mcp config set auto_watch false 設定 auto_watch = false，並部署根 .cbmignore。
3. 查閱 mcp-configuration-guide.md 中的完整規格。

階段 4：以 Agent 為優先的設計系統 Linting（@shadcn/lint）

1. 安裝 @shadcn/lint 並使用 eslint.config.mjs.template 配置 ESLint flat config。
2. 查閱 styling-and-linting-guide.md 中的機制。

階段 5：獨立生產 Docker 與反向代理（Traefik / Nginx）

1. 在 next.config.ts 中：解析 Git 提交哈希（getGitCommitHash() 含 CI 後備方案）和套件版本，在 env 下注入 NEXT_PUBLIC_APP_VERSION 和 NEXT_PUBLIC_GIT_COMMIT_HASH，啟用 output: "standalone"，為版本偏移保護設定 deploymentId（${pkg.version}-${gitHash}），配置帶有 X-Accel-Buffering: no 的 headers，並設定 experimental.serverActions.allowedOrigins。
2. 在 .env.example 中記錄 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY，並將其傳遞給執行階段環境。
3. 部署 Dockerfile.template（含 STOPSIGNAL SIGTERM）和 docker-compose.yml.template（含 stop_grace_period: 30s）。
4. 反向代理配置：
   • Traefik：部署 docker-compose.prod.yml.template，其中包含動態環境變數標籤（${DOMAIN_NAME}、${TRAEFIK_ENTRYPOINT}、${TRAEFIK_CERTRESOLVER}）和抗緩衝中介軟體。
   • Nginx：將 nginx-site.conf.template 部署或輸出到 /etc/nginx/sites-available/<domain> 以搭配 Certbot SSL 憑證。
5. 查閱 docker-containerization-guide.md 中的架構和多容器快取偏移注意事項。

階段 6：Git Hooks 與信用優化 CI/CD

1. 安裝 husky、@commitlint/cli、@commitlint/config-conventional。
2. 配置 commitlint.config.mjs.template、.husky/commit-msg 和 .husky/pre-push（pnpm run test:all）。
3. 部署 .github/workflows/release-please.yml，其中包含 .next/cache 建置快取和多架構矩陣發佈。
4. 查閱 cicd-and-release-automation-guide.md 中的快取功能。

階段 7：最終執行報告與驗證

1. 執行配置驗證腳本，並確保所有檢查通過。
2. 根據規則 36，將所有創建/修改的檔案加入 git 暫存區（git add .）。
3. 強制性最終輸出：渲染完整、結構化的 Next.js 開發環境設定執行報告 Markdown 表格，總結所有已實作的檔案、驗證檢查結果以及後續開發步驟。

---

驗證與完整性檢查

• 執行配置驗證腳本：
  • Windows (PowerShell)：powershell -ExecutionPolicy Bypass -File .agents/skills/nextjs-dev-setup/scripts/verify-project-config.ps1
  • Linux / macOS (Bash)：bash .agents/skills/nextjs-dev-setup/scripts/verify-project-config.sh
• 修復任何回報的錯誤，並重新驗證，直到所有檢查通過。

---

邊緣案例與已知 AI 陷阱

• 鏈結命令：切勿在終端機執行中使用 && 或 ; 在同一行鏈結命令。
• MCP 停用：在 AG 全域配置中，agy.exe 會忽略 mcpServers 內的 "disabled": true。請將已停用的伺服器移出 mcpServers。
• Docker 映像名稱：Docker OCI 命名嚴格要求小寫的儲存庫名稱（IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')）。
• Storybook Intl 上下文：始終使用 NextIntlClientProvider 包裝渲染 Link 或 useTranslations 的 Storybook 故事。

---

強制性最終輸出：執行報告範本

完成技能工作流程後，始終輸出此報告：

## 🛠️ Next.js 開發環境設定執行報告

| 步驟 / 元件                      | 目標檔案 / 資源                                                                                               | 狀態                             | 備註 / 詳細資訊                                                                     |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------- | :--------------------------------------------------------------------------------- |
| **1. 專案中繼資料**              | `docs/project.json`                                                                                            | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 配置了套件管理器、目錄、動畫與 i18n 中繼資料。                                      |
| **2. 應用程式圖示與 PWA Manifest** | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                                     | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 使用使用者提供的 favicon 配置了根 favicon、Apple touch icon 和 Web App Manifest。 |
| **3. 核心依賴項**               | `package.json`, Lockfile                                                                                       | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 驗證了 React、Next.js、樣式和動畫函式庫。                                           |
| **4. Next.js 開發伺服器 MCP**    | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json`         | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 為 AG 和工作區全域配置了 Next.js Dev Server（`next-devtools`）。                   |
| **5. Playwright 與即時測試**     | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`               | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 驗證了執行器、瀏覽器、Playwright MCP 與 `@next/playwright` 即時導航輔助工具。        |
| **6. 程式碼庫記憶體與口吃修復** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`                          | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 註冊了 MCP，配置了 .cbmignore 排除項，並停用了 session watcher。                    |
| **7. Jest 單元測試**             | `jest.config.ts`, `jest.setup.ts`                                                                              | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 配置了 Next.js Jest 轉換器、jsdom 環境與 test-dom。                                 |
| **8. Storybook 與 Storybook MCP** | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`            | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 為全域和工作區配置了 Storybook Vite、a11y、主題以及 Storybook AI MCP。              |
| **9. 以 Agent 為優先的 Tailwind Linter** | `eslint.config.mjs`, `package.json`                                                                            | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 配置了 `@shadcn/lint` 用於 Agent 對設計令牌和合約的驗證。                           |
| **10. Docker 與反向代理**        | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                                    | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 獨立容器、Traefik 標籤 / 使用 Certbot SSL 的 Nginx HTTPS。                          |
| **11. Husky Git Hooks**          | `.husky/commit-msg`, `.husky/pre-push`                                                                         | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 強制執行雙重 pre-push 測試套件（Jest + Playwright）與 commitlint。                |
| **12. Commitlint 配置**          | `commitlint.config.mjs`                                                                                        | `[IMPLEMENTED]` / `[UNTOUCHED]`  | 配置了 `@commitlint/config-conventional`。                                          |
| **13. Release 與 CI 建置快取**   | `.github/workflows/release-please.yml`                                                                         | `[IMPLEMENTED]` / `[UNTOUCHED]`  | Next.js 建置快取 (.next/cache)、SemVer 版本發佈 PR 以及 GHCR 多架構套件。         |
| **14. 環境驗證**                 | `scripts/verify-project-config.ps1` / `.sh`                                                                    | `[PASSED]`                       | 完整性檢查通過，零錯誤。                                                             |

#### 狀態定義：
- **`[IMPLEMENTED]`**：在此次設定運行期間新創建、安裝或修改。
- **`[UNTOUCHED]`**：在執行技能之前已正確配置；保留原樣。
- **`[SKIPPED]`**：根據使用者偏好故意省略。