PHP 遷移實戰：從 Windows 到 Linux 的三大坑與解決方案

PHP 遷移實戰：Windows → Linux 三大核心問題與修復

研發在 Windows + PHP 環境開發完成，部署至 Linux + Apache + PHP 後程序不工作，且無錯誤日志。經排查發現三大典型問題：擴展缺失、cURL 不支持 HTTPS、GD 不支持 JPEG。本文記錄完整排查與修復過程。

問題 1：擴展缺失導致靜默失敗

現象：Apache error.log 無報錯，頁面空白或功能異常。
排查：與研發核對 php -m，發現缺少關鍵擴展（如 mysqli、pdo_mysql、json 等）。
修復：通過包管理器或源碼編譯安裝缺失擴展：

# Ubuntu/Debian
apt-get install php-mysql php-pdo php-json php-mbstring php-xml php-curl php-gd

# CentOS/RHEL
yum install php-mysqlnd php-pdo php-json php-mbstring php-xml php-curl php-gd

# 重啟 Apache
systemctl restart httpd  # 或 apache2

安裝後程序恢復正常。

問題 2：cURL 不支持 HTTPS（CURLE_UNSUPPORTED_PROTOCOL）

現象：微信支付等 HTTPS 請求失敗，錯誤碼 1 (CURLE_UNSUPPORTED_PROTOCOL)。
原因：系統自帶 cURL 未啟用 SSL 支持（未鏈接 OpenSSL/LibreSSL）。
修復：重新編譯帶 SSL 的 cURL 並重建 PHP cURL 擴展

# 1. 編譯安裝 cURL（指定 --with-ssl）
wget https://curl.se/download/curl-7.88.0.tar.gz
tar xzf curl-7.88.0.tar.gz && cd curl-7.88.0
./configure --with-ssl --prefix=/usr/local/curl
make && make install

# 2. 重建 PHP cURL 擴展（假設 PHP 安裝在 /usr/local/php5.5）
cd /path/to/php-5.5.38/ext/curl
/usr/local/php5.5/bin/phpize
./configure --with-curl=/usr/local/curl --with-php-config=/usr/local/php5.5/bin/php-config
make && make install

# 3. 確認 php.ini 已載入 extension=curl.so，優雅重啟 Apache
/usr/local/apache2/bin/apachectl -k graceful

問題 3：GD 庫默認不支持 JPEG

現象：圖片處理功能報錯 gd-jpeg: JPEG library reports unrecoverable error 或輸出損壞。
修復：重新編譯 GD 擴展啟用 JPEG 支持

cd /path/to/php-5.5.38/ext/gd
/usr/local/php5.5/bin/phpize
./configure --with-php-config=/usr/local/php5.5/bin/php-config --with-jpeg-dir=/usr/lib  # 或 /usr/local/lib
make && make test && make install

# 重啟 Apache
/usr/local/apache2/bin/apachectl -k graceful

遷移檢查清單（防坑指南）

1. 大小寫敏感：Linux 文件系統區分大小寫，include 'Config.php' 與 config.php 不同。
2. 路徑分隔符：統一使用 DIRECTORY_SEPARATOR 或 /。
3. 權限問題：storage/、cache/、logs/ 需 www-data 寫權限。
4. 時區設置：php.ini 設 date.timezone = Asia/Shanghai。
5. 擴展一致性：php -m 對比開發與生產環境差異。
6. 依賴庫版本：OpenSSL、libcurl、libjpeg、libpng、freetype 版本盡量一致。

總結

PHP 跨平台遷移核心在於運行時一致性：擴展集合、依賴庫能力、文件系統語義、權限模型。建議採用 Docker 容器化交付，將「編譯好擴展的鏡像」作為構建產物，徹底消除環境差異。