測試用例管理平台維護實戰：環境搭建、性能優化與 PHP 版本兼容性攻堅

項目背景

接手維護一套內部測試用例管理平台，核心功能涵蓋用例存儲、查詢、管理、評審流程。平台基於 PHP + MySQL 構建，歷經多版本迭代，存在技術債務亟待清理。本文記錄本地環境還原、前端資源優化、郵件評審功能修復三大核心任務的實踐過程。

一、本地環境快速還原

技術棧版本鎖定

• Web 服務器：Apache 2.4（通過 XAMPP 集成）
• PHP 版本：線上 7.1 → 本地 8.1（需解決兼容性問題）
• 數據庫：MySQL 5.7
• 框架：自研輕量 MVC，無 Composer 依賴管理

環境搭建步驟

1. 安裝 XAMPP，啟動 Apache + MySQL 服務
2. 將源碼部署至 htdocs/platform/ 目錄
3. 導入數據庫結構與基礎數據
4. 修改 config/database.php 對應本地連接信息
5. 配置 Apache 虛擬主機（可選），訪問 https://localhost/platform/ 驗證

二、前端資源加載優化

問題現象

首頁加載耗時 > 8s，F12 Network 面板顯示多個 JS/CSS 請求狀態為 (pending) 或 404 Not Found，主要為：

• 引用已下線的第三方 CDN 資源（如舊版 jQuery UI、Bootstrap CDN）
• 內部遷移導致的相對路徑失效
• 重複引入同一庫的不同版本

解決方案

// 優化前（片段）
<script src="https://cdn.bootcss.com/jquery/1.11.3/jquery.min.js"></script>
<script src="/static/js/old-plugin.js"></script> <!-- 404 -->
<link rel="stylesheet" href="https://cdn.example.com/removed.css"> <-- 連接超時 -->

// 優化後
<!-- 本地化核心庫，版本鎖定 -->
<script src="/static/vendor/jquery-3.6.0.min.js"></script>
<script src="/static/vendor/bootstrap-4.6.2.min.js"></script>
<!-- 移除失效引用，合並壓縮業務代碼 -->
<script src="/static/dist/app.min.js?v=20240115"></script>

優化效果

• HTTP 請求數從 42 減至 18
• 首屏加載時間從 8.2s 降至 1.5s
• 消除所有控制台紅色報錯

三、用例評審郵件功能修復

故障現象

觸發評審流程時，郵件發送失敗，PHP 報錯：

Fatal error: Call-time pass-by-reference has been removed in D:\xampp\htdocs\platform\modules\review\mail.php on line 42

根因分析

PHP 版本差異導致的語法不兼容：

• 線上環境 PHP 5.6/7.0 允許調用時傳引用：func(&$var)
• 本地 PHP 8.1 已移除此特性（自 PHP 5.4 棄用，8.0 完全移除）

代碼對比修復

// 問題代碼（舊版風格）
function sendMail(&$to, &$subject, &$body) { ... }
sendMail($to, $subject, $body); // 調用時加 & 會報錯

// 修復方案：函數定義聲明引用，調用時正常傳值
function sendMail(&$to, &$subject, &$body) { ... } // 定義保持引用
sendMail($to, $subject, $body); // 調用去掉 &

// 或更現代的寫法：返回值/對象封裝
function sendMail(array $params): bool {
    $to = $params['to'];
    $subject = $params['subject'];
    $body = $params['body'];
    // ...
}
sendMail(['to' => $to, 'subject' => $subject, 'body' => $body]);

全項目兼容性掃描與修復

使用 phpcs + 自定義規則掃描全項目，共發現 23 處調用時傳引用，全部按上述模式修復。同時處理了：

• each() 棄用替換為 foreach
• create_function() 替換為匿名函數
• get_magic_quotes_gpc() 移除相關邏輯

四、經驗總結與最佳實踐

1. 版本鎖定文件化：在項目根目錄維護 .php-version 或 composer.json 的 require.php 字段，CI/CD 管道強制校驗。
2. 漸進式升級策略：PHP 5.6 → 7.4 → 8.1 分階段驗證，每階段跑全量測試用例。
3. 靜態分析納入流程：集成 PHPStan (Level 5+) + Psalm，攔截類似棄用語法、類型不匹配等問題。
4. 前端資源本地化原則：核心依賴（jQuery、Vue、Bootstrap 等）必須本地化存放，構建流程引入版本號哈希緩存策略。
5. 遺留系統接管清單：環境還原、依賴梳理、煙霧測試、性能基線、安全掃描、文檔更新——六步走不可省略。

結語

老系統維護的核心不在於「重寫」，而在於「可控演進」。通過環境標準化、靜態分析護航、增量重構，讓十年歷史代碼庫在 PHP 8.x 時代煥發新生，這才是維護工程師的核心價值。