# WordPress 升級計畫

## 進度

- [x] 蒐集資訊
- [x] 推薦版本
- [x] 分析相容性
- [x] 確認方案
- [ ] 備份與截圖基準
- [ ] 升級核心與外掛
- [ ] 逐一啟用外掛與驗證
- [ ] 本機收尾與產出接手文件
- [ ] 測試機 / 測試站升級
- [ ] 正式站升級
- [ ] 歸檔與提交

## 環境資訊

### 基本環境

| 項目 | 值 |
|---|---|
| WordPress 版本 | 6.1.10（multisite） |
| PHP 版本 | 7.4（docker 影像 `steps/php7.4`） |
| 資料庫大小 | 約 630 MB |
| 站台網址（正式站） | https://www.im.fju.edu.tw |
| 站台網址（測試站） | https://imtestwebside.fju.edu.tw/ |
| mu-plugins | 無 |
| Drop-ins | 無 |
| 第三方 Webhook / REST API | 無 |
| 測試環境 | 測試站（與正式站同台 server，共用 PHP 版本與 DB server，僅 WP 站台獨立） |

### .htaccess 安全規則

已有 `RewriteCond %{REQUEST_URI} /\.` 規則，`.upgrades/` 目錄不會被外部存取

### 啟用中的外掛（27 個）

**Network active（24 個）**

| 外掛 | 版本 | 來源 | Tested up to | 備註 |
|---|---|---|---|---|
| Advanced Cron Manager | 2.5.2 | 公開 | 6.3 | |
| Advanced Editor Tools (TinyMCE Advanced) | 5.9.2 | 公開 | 6.3 | |
| All-in-One WP Migration | 7.79 | 公開 | 6.4 | |
| All in One SEO | 4.5.0 | 公開 | 6.4.1 | |
| Custom Login Page Customizer | 2.3.1 | 公開 | 6.4 | |
| Duplicate Post | 3.2.4 | 公開 | 5.4 | |
| Elementor | 3.17.3 | 公開 | 6.4 | |
| Elementor Pro | 3.17.1 | 付費 | — | 可透過 API 下載，已測試成功（hook home_url 為正式站網址） |
| Employee Spotlight | 4.9.8 | 公開 | 6.2 | |
| Enhanced Media Library | 2.8.9 | 公開 | 5.8.3 | |
| Health Check & Troubleshooting | 1.7.0 | 公開 | 6.3 | |
| Hide Page And Post Title | 1.5.7 | 公開 | 6.2 | |
| Loco Translate | 2.6.6 | 公開 | 6.3.1 | |
| Page Builder by SiteOrigin | 2.28.0 | 公開 | 6.4 | |
| Rich-Web Tabs（本地 slug `tabbed`） | 1.3.9 | 公開 | — | 本地 slug 與 wp.org `tabs-rich-web` 不一致，WP-CLI 無法自動升級 |
| SiteOrigin Widgets Bundle | 1.56.0 | 公開 | 6.3 | |
| Social LikeBox & Feed（facebook-by-weblizar） | 3.1.4 | 公開 | 6.4 | |
| TablePress | 2.2.3 | 公開 | 6.4 | |
| Team Members | 5.3.0 | 公開 | 6.4 | |
| UpdraftPlus | 1.23.12 | 公開 | 6.4 | |
| WPBakery Page Builder (js_composer) | 5.4.5 | 付費 | — | API 需 license，DB 無 key，無法自行下載新版 |
| wpDataTables (Lite) | 2.1.75 | 公開 | 6.3 | |
| WP Headers And Footers | 2.2.0 | 公開 | 6.5 | |
| WPS Hide Login | 1.9.9 | 公開 | 6.3 | |

**Per-site active（3 個）**

| 外掛 | 版本 | 來源 | Tested up to | 備註 |
|---|---|---|---|---|
| OptinMonster | 2.16.4 | 公開 | 6.5 | |
| UserFeedback Lite | 1.0.16 | 公開 | 6.5.2 | |
| WPForms Lite | 1.8.9.6 | 公開 | 6.6 | |

### 已停用的外掛（3 個）

| 外掛 | 版本 | 功能 | 處理 |
|---|---|---|---|
| Happy Elementor Addons | 3.9.1.1 | Elementor 編輯器額外元件 | 待客戶確認保留或移除（Phase 4 已列入客戶摘要） |
| reCaptcha by BestWebSoft（google-captcha） | 1.73 | 表單防機器人驗證 | 待客戶確認保留或移除 |
| Redirection | 5.3.10 | 301 網址轉址管理 | 待客戶確認保留或移除 |

### 主題

| 主題 | 版本 | 狀態 | Tested up to |
|---|---|---|---|
| OceanWP | 3.5.1 | 啟用中（網路） | 6.4 |

**未啟用的主題（8 個）**：education-base、innovation-lite、panoramic、parabola、twentyfifteen、twentynineteen、twentyseventeen、twentysixteen
（待客戶確認保留或移除，Phase 4 已列入客戶摘要）

### 團隊歷次升級紀錄

本分支目前停留在 6.1.10。同 repo 其他站台分支中，6.1.10 之後已被團隊實戰升級過的版本：

- WP 6.6.5：`scu-disadvantage-care` 分支從 6.0.3 升級完成（commit `3ab28d2` 升級、`9aaa92b` 測試機升級完成、`8c97fc5` 正式機升級完成）

PHP 與 WP 6.7 以上的版本，目前同團隊各分支皆無實戰升級紀錄（PHP 仍維持 7.4）

### Elementor Pro 下載方式

使用 `\ElementorPro\License\API::get_plugin_package_url($version)` 下載指定版本。API 使用 `home_url()` 做網域驗證，本機需要 hook `home_url` filter 改為正式站網址 `https://www.im.fju.edu.tw`。已測試成功，可在容器內直接下載

### 外掛來源分類

全數判定為「公開」或「付費」，**無自製外掛**。已請使用者確認分類無誤

- **付費外掛**：Elementor Pro（已驗證 API 可下載）、WPBakery (js_composer)（API 需 license，DB 無 key）
- 其餘為公開外掛

## 升級路徑

### 整體升級路徑

```
第一段：WordPress 6.1.10 → 6.6.5（維持 PHP 7.4）
第二段：WordPress 6.6.5 → 6.9.4（維持 PHP 7.4）
第三段：PHP 7.4 → 8.3（WordPress 已在 6.9.4）
```

### 最終目標

- WordPress：6.9.4
- PHP：8.3

### 中繼點選擇理由

選擇 6.6.5 作為中繼點：
1. 同團隊另一個分支（`scu-disadvantage-care`）已從 6.0.3 實戰升級到 6.6.5（commit `3ab28d2` / `9aaa92b` / `8c97fc5`）
2. 多數外掛的 Tested up to 集中在 6.3 ~ 6.6 之間
3. 從 6.1.10 跨 5 個大版本到 6.6.5 屬於合理上限，再大就難以定位問題

PHP 目標選 8.3 而非 8.5：8.5 為新近版本，生態系成熟度尚需觀察；8.3 為 WP 6.6.6 至 6.9.x 完整支援範圍內、且為 PHP 官方仍在 active support 的較高穩定版本，較保守。同團隊無 PHP 升級實戰紀錄可參考，採 Skill 預設原則折中為 8.3

WP 7.0 已釋出但發布不到一個月，依 Skill 規則暫不升，等小版本修正後再考慮

### 升級策略

先升 WordPress 再升 PHP。本機、測試站、正式站交替進行

**PHP 段特殊處理**：測試站跟正式站共用 server PHP，PHP 升級會同時生效在正式站，無法獨立先測。PHP 升級第三段直接「本機 → 正式站」，跳過測試站階段

### 本段範圍

**本資料夾（`2026-06-03_wp-6.1.10-to-6.6.5/`）為第 1 段**：6.1.10 → 6.6.5（PHP 7.4 維持）。第 2、3 段在各自開始前建立資料夾

### 預估時程

| 步驟 | 環境 | 動作 | 預估時間 |
|---|---|---|---|
| 1 | 本機 | WordPress 6.1.10 → 6.6.5 + 測試 | 1 ~ 2 天 |
| 2 | 測試站 | WordPress 6.1.10 → 6.6.5 + 測試 | 半天 ~ 1 天 |
| 3 | 測試站 | 客戶驗證 WordPress 6.1.10 → 6.6.5 | 1 ~ 2 天 |
| 4 | 正式站 | WordPress 6.1.10 → 6.6.5 + 觀察 | 1 ~ 2 週 |
| 5 | 本機 | WordPress 6.6.5 → 6.9.4 + 測試 | 1 ~ 2 天 |
| 6 | 測試站 | WordPress 6.6.5 → 6.9.4 + 測試 | 半天 ~ 1 天 |
| 7 | 測試站 | 客戶驗證 WordPress 6.6.5 → 6.9.4 | 1 ~ 2 天 |
| 8 | 正式站 | WordPress 6.6.5 → 6.9.4 + 觀察 | 1 ~ 2 週 |
| 9 | 本機 | PHP 7.4 → 8.3 + 測試 | 1 ~ 2 天 |
| 10 | 正式站 | PHP 7.4 → 8.3 + 觀察 | 1 ~ 2 週 |

合計預估（含客戶決策與排程緩衝）：約 7 ~ 11 週

## 相容性分析

### 核心自訂修改

**無**。git log 顯示所有非版本升級 commit（`ff4589f3`、`f100c36c`）只動 `wp-config-sample.php` 模板和 docker 設定檔，不影響核心升級

### 外掛升級版本（目標 WP 6.6.5 / PHP 7.4）

| 外掛 | 目前版本 | 建議升級版本 | 風險 | 資料庫 | 授權過期行為 |
|---|---|---|---|---|---|
| Advanced Cron Manager | 2.5.2 | 2.7.0 | 低 | 無自訂資料表 | — |
| Advanced Editor Tools (TinyMCE Advanced) | 5.9.2 | 5.9.2（已是最新） | 低 | 無自訂資料表 | — |
| All-in-One WP Migration | 7.79 | 7.105 | 低 | 無自訂資料表 | — |
| All in One SEO | 4.5.0 | 4.9.7.2 | 低 | 有自動 migration | — |
| Custom Login Page Customizer | 2.3.1 | 2.5.4 | 低 | 無自訂資料表 | — |
| Duplicate Post | 3.2.4 | 4.5 | 中 | 無自訂資料表 | — |
| Elementor | 3.17.3 | 3.33.6 | 中 | 有自動 migration | — |
| Elementor Pro | 3.17.1 | 3.33.2 | 中 | 有自動 migration | 只鎖更新（外掛官方說明） |
| Employee Spotlight | 4.9.8 | 5.1.5 | 低 | 無自訂資料表 | — |
| Enhanced Media Library | 2.8.9 | 2.9.4 | 低 | 無自訂資料表 | — |
| Health Check & Troubleshooting | 1.7.0 | 1.7.1 | 低 | 無自訂資料表 | — |
| Hide Page And Post Title | 1.5.7 | 1.5.8 | 低 | 無自訂資料表 | — |
| Loco Translate | 2.6.6 | 2.8.5 | 低 | 無自訂資料表 | — |
| OptinMonster | 2.16.4 | 2.16.24 | 低 | 無自訂資料表 | — |
| Page Builder by SiteOrigin | 2.28.0 | 2.34.3 | 低 | 無自訂資料表 | — |
| Rich-Web Tabs（本地 `tabbed`） | 1.3.9 | 維持 | 低 | 無自訂資料表 | — |
| SiteOrigin Widgets Bundle | 1.56.0 | 1.73.1 | 低 | 無自訂資料表 | — |
| Social LikeBox & Feed | 3.1.4 | 3.1.5 | 低 | 無自訂資料表 | — |
| TablePress | 2.2.3 | 3.2.8 | 中 | 有自動 migration | — |
| Team Members | 5.3.0 | 5.4.1 | 低 | 無自訂資料表 | — |
| UpdraftPlus | 1.23.12 | 1.26.4 | 低 | 無自訂資料表 | — |
| UserFeedback Lite | 1.0.16 | 1.11.2 | 低 | 無自訂資料表 | — |
| WPBakery (js_composer) | 5.4.5 | 待 PM 提供新版 zip 或 license | 高 | 有 shortcode mapping 資料，覆蓋檔案即可 | 只鎖更新（從 `class-vc-updater.php` 程式碼確認） |
| wpDataTables (Lite) | 2.1.75 | 6.5.0.8 | 中 | 大幅資料表結構變動，需特別驗證 | — |
| WPForms Lite | 1.8.9.6 | 1.10.1 | 低 | 有自動 migration | — |
| WP Headers And Footers | 2.2.0 | 3.1.4 | 低 | 無自訂資料表 | — |
| WPS Hide Login | 1.9.9 | 1.9.18 | 低 | 無自訂資料表 | — |

> 版本支援範圍見 `.upgrades/compat/plugins/`

**特殊處理說明**：

- Elementor 不升到最新的 4.1.1，因 3.34+ 起 `Requires at least` 提升為 WP 6.7，6.6.5 環境下最後相容版本是 3.33.6（已從 readme.txt 驗證）
- Elementor Pro 同理，6.6.5 環境下最後相容版本是 3.33.2
- Duplicate Post 4.6 需要 WP 6.8，6.6.5 環境用 4.5
- TablePress 3.3+ 需要 WP 6.7，6.6.5 環境用 3.2.8
- Social LikeBox & Feed 不升到 wp.org 標示的最新版 3.2.0，因 3.2.0 的 readme.txt `Tested up to 6.9.1` 與 `Requires at least 7.4` 互相矛盾（WP 7.4 尚未發佈），對 WP 6.x 的相容性無官方測試保證，保守選 3.1.5。**WordPress 不會 enforce `Requires at least` 擋安裝**（已實測，見 `compat/plugins/facebook-by-weblizar.md`）

### 外掛依賴群組

| 群組 | 外掛 | 依賴方向 | 說明 |
|---|---|---|---|
| 1 | Elementor、Elementor Pro | Pro → 免費版 | Pro 3.33.2 必須搭配 Elementor 3.33.x，啟用順序：先免費版，後 Pro |

### 主題升級版本

| 主題 | 目前版本 | 建議升級版本 | 是否需要切換預設主題 | 說明 |
|---|---|---|---|---|
| OceanWP | 3.5.1 | 4.1.6 | 建議切換 | 主版本跨度 3 → 4，Tested up to 7.0，升級後需視覺驗證 |

### 待客戶確認事項（已列入客戶摘要）

1. WPBakery Page Builder 授權狀態（PM 訊息已產出）
2. 3 個停用外掛是否保留（Happy Elementor Addons、google-captcha、Redirection）
3. 8 個未啟用主題是否保留（Education Base / Innovation Lite / Panoramic / Parabola 及 4 個 Twenty 系列）

### 外掛啟用測試順序

逐一啟用測試的順序（風險由低到高、依賴在前）：

1. 風險低的工具型外掛（Advanced Cron Manager、Health Check、TinyMCE Advanced、Hide Page And Post Title、WPS Hide Login、WP Headers And Footers、Loco Translate）
2. SEO / 備份類（All in One SEO、All-in-One WP Migration、UpdraftPlus）
3. 內容展示類（Employee Spotlight、Team Members、Enhanced Media Library、Custom Login Page Customizer、Duplicate Post、Social LikeBox & Feed）
4. SiteOrigin 群組（Page Builder by SiteOrigin、SiteOrigin Widgets Bundle）
5. 表格 / 資料類（TablePress、wpDataTables）
6. 行銷 / 表單類（OptinMonster、UserFeedback Lite、WPForms Lite）
7. Elementor 群組（先 Elementor、後 Elementor Pro）
8. WPBakery（最後啟用，視 PM 回覆決定版本）

### 關鍵阻擋點

**Phase 5 之前必須先取得 WPBakery 新版 zip 或 license**，否則第 1 段升級無法啟動。WPBakery 5.4.5（2018 年發佈）對 WP 6.6.5 已跨 5 個大版本、6 年沒升級，預期會嚴重出問題

## 確認方案

### 升級方式

`wp core update --version=6.6.5 --allow-root --network`（WP-CLI 指定版本升級，一次處理 multisite 所有 sites）

### 外掛升級清單

見上方〈相容性分析〉的「外掛升級版本」表格，已確認不需要調整

### 付費外掛處理方式

- **Elementor Pro**：透過 `\ElementorPro\License\API::get_plugin_package_url('3.33.2')` 在容器內直接下載（hook `home_url` 為 `https://www.im.fju.edu.tw`），不需要找 PM 要帳號
- **WPBakery (js_composer)**：需 PM 提供 license 或新版 zip（PM 訊息已產出，見 `pm-message.md`）。授權過期屬「只鎖更新」（已從 `class-vc-updater.php` 程式碼確認），不影響已安裝功能

### 已停用的外掛和主題

見上方〈相容性分析〉的「待客戶確認事項」。客戶摘要中已列出，PM 拿到回覆前升級流程不處理

### 自動化測試

採用 agent-browser 自動測試：每個外掛啟用後檢查前 / 後台無 PHP error、自動開外掛設定頁、視覺判斷部分截圖請使用者確認

### 客戶摘要 & PM 訊息

- 客戶摘要：見 `customer-summary.md`
- PM 訊息：見 `pm-message.md`

需在啟動 Phase 5 之前送出給 PM 並等待 WPBakery 授權回覆