在 Linux (CentOS/RHEL) 上讓 PHP 連接 Microsoft SQL Server,需依序編譯安裝 FreeTDS → mssql (舊擴充) → pdo_dblib (PDO 驅動)。本文記錄無坑編譯參數、配置修正與連線驗證全流程。
phpize、php-config 路徑一致 (如 /usr/local/php/bin/)。cd freetds-1.00.x
./configure --prefix=/usr/local/freetds \
--enable-msdblib \
--enable-sybase-compat \
--disable-threadsafe \
--with-openssl=/usr/include/openssl # 可選,支援 TLS
make && make install
cd php-7.0.x/ext/mssql
/usr/local/php/bin/phpize
./configure --with-php-config=/usr/local/php/bin/php-config --with-mssql=/usr/local/freetds
make && make install
PHP 7.1+ **已移除 mssql 擴充**,請直接使用 pdo_dblib (PDO) 或 sqlsrv (Microsoft 官方驅動,僅限 Windows/Linux 官方包)。
cd php-7.x.x/ext/pdo_dblib
/usr/local/php/bin/phpize
./configure --with-php-config=/usr/local/php/bin/php-config --with-pdo-dblib=/usr/local/freetds
make && make install
extension=pdo_dblib.so
; extension=mssql.so (僅 PHP 5.6/7.0 需要)
重啟 php-fpm / Apache:systemctl restart php-fpm 或 apachectl graceful。
/usr/local/freetds/etc/freetds.conf[global]
tds version = 8.0 # SQL Server 2008+ 使用 8.0 (TDS 7.4)
client charset = UTF-8 # 關鍵:解決中文亂碼
text size = 64512 # 避免長文本截斷
# 具名實例範例 (可選)
[mssql]
host = 192.168.1.100
port = 1433
tds version = 8.0
/usr/local/freetds/bin/tsql -H 192.168.1.100 -p 1433 -U sa -P 'password' -D dbname
成功會進入 `1>` 提示符,輸入 `SELECT @@VERSION; GO` 驗證。
$dsn = 'dblib:host=192.168.1.100:1433;dbname=your_db;charset=utf8';
$pdo = new PDO($dsn, 'sa', 'password', [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_EMULATE_PREPARES => false, // 使用真實預備語句
]);
關鍵:DSN 中 **必須包含埠號** (`host=ip:port`),否則 FreeTDS 預設尋找 1433 但某些環境會失敗。
| 錯誤現象 | 原因 | 解決 |
|---|---|---|
| Adaptive Server is unavailable or does not exist | 埠號未指定/防火牆阻擋/實例名錯誤 | DSN 加 :1433、開放防火牆、確認 SQL Browser 服務 |
| 中文亂碼/問號 | freetds.conf 缺 client charset | 加入 client charset = UTF-8 |
| 編譯失敗: ld: cannot find -lsybdb | FreeTDS 庫路徑未加入 ldconfig | echo "/usr/local/freetds/lib" > /etc/ld.so.conf.d/freetds.conf && ldconfig |
| PDO 驅動未找到 | php.ini 未載入 pdo_dblib.so | php -m | grep pdo_dblib 確認,檢查 extension_dir |