Microsoft Drivers for PHP for SQL Server 的系統需求

本文列出你必須在系統上安裝的元件，才能透過 SQLSRV 或 PDO_SQLSRV 任一驅動程式存取 SQL Server 或 Azure SQL Database 資料。

欲了解更多關於 PHP 驅動程式的支援生命週期與需求，請參閱支援矩陣。每個版本中的 SQLSRV 與 PDO_SQLSRV 驅動程式擁有相同的 PHP、作業系統、架構、執行緒安全與 ODBC 要求。

驅動程式堆疊如何相互配合

PHP 應用程式不直接連接到資料庫伺服器。每一層必須與其隔壁的另一層相容：

階層	你選擇或設定的內容	不符時的顯示方式
Application	SQLSRV 函式或PDO_SQLSRV類別與屬性	未定義的函式、無法取得的 PDO 驅動程式，或應用程式層級錯誤
PHP 擴充功能	為 PHP 小版本、架構與執行緒安全模式所建置的 SQLSRV 及 PDO_SQLSRV 檔案	PHP 啟動警告、模組載入失敗或程序當機
PHP 執行環境	命令列介面（CLI）、Apache 模組、PHP-FPM 或 IIS FastCGI 配置	CLI 會載入驅動程式，但網頁應用程式不會
Microsoft ODBC 驅動程式	所選 PHP 驅動程式版本支援的版本	連線失敗或缺少 ODBC 函式庫
作業系統	一個支援的版本與架構，並具備必要的執行時與建置套件	無相容套件、未解決的共享函式庫，或原始碼編譯失敗
資料庫產品	受支援的 SQL Server 或 Azure SQL 目標	連線建立後的伺服器版本或功能特定錯誤

SQLSRV 和 PDO_SQLSRV 在同一 ODBC 驅動程式上提供不同的 PHP API。當應用程式同時使用兩個 API 時，請同時安裝兩者。安裝一個擴充功能並不會自動安裝或啟用另一個。

API	程式設計模型	安裝特定檢查
SQLSRV	程序函式 `sqlsrv_*` 與 SQLSRV 常數	`extension_loaded('sqlsrv')` 與 `function_exists('sqlsrv_connect')`
PDO_SQLSRV	PHP 資料物件（PDO）類別、屬性與例外	`extension_loaded('pdo_sqlsrv')` 中的 `sqlsrv` 和 `PDO::getAvailableDrivers()`

這些延伸部分可以獨立安裝。 PDO_SQLSRV也要求 PDO 在 PDO_SQLSRV 前載入。

選擇相容的組合

在下載或編譯驅動程式前，請先完成以下檢查：

識別每個服務該應用程式的 PHP 執行環境。排程任務、命令列工作程式、IIS 網站、Apache 模組與 PHP-FPM 池皆可使用不同的 PHP 執行檔與設定檔。
對每個 PHP 執行檔執行以下指令：
```
php -i | findstr /I "PHP Version Architecture Thread Safety extension_dir"
```
在 Linux 或 macOS 上，請使用：
```
php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"
```
file 指令回報執行檔的架構。如果它回報一個通用 macOS 可執行檔，請明確選擇預期架構，例如 arch -arm64 php --version 或 arch -x86_64 php --version。建置、載入和測試擴充時，請使用相同的架構選擇。
選擇支援 PHP 小版本、作業系統及資料庫目標的 PHP 驅動版本。
從本文相容性表中選擇支援的 Microsoft ODBC 驅動程式版本。
將擴充檔或 PIE 編譯版本與 PHP 架構及執行緒安全模式相匹配。除非所有這些數值都相符，否則不要從其他 PHP 安裝複製擴充功能。
請分別配置並驗證 CLI 與網頁伺服器執行時。成功執行 php -m 指令僅證明 CLI 執行階段已載入該擴充功能。

PHP

從 PHP 網站下載 PHP 二進位檔。請選擇 PHP 版本支援中列出的 PHP 版本。

啟用與你 PHP 版本相符的驅動程式檔案。如需檔案名稱，請參見驅動程式版本。從下載 Microsoft Drivers for PHP for SQL Server下載檔案。關於設定說明，請參見「載入 Microsoft Drivers for PHP for SQL Server」。
選擇 PHP 和你的應用框架所支援的網頁伺服器與 PHP 整合方法。請依照 PHP 安裝說明和框架的部署說明，設定網頁伺服器執行 PHP。在網頁伺服器執行時與 CLI 分開驗證擴充功能的載入。

執行緒安全與架構

PHP 建置與擴充檔在這兩個值上都必須一致。

PHP 值	必須選擇驅動程式
`Thread Safety => enabled`	執行緒安全（`ts` 或 `TS`）驅動程式檔案
`Thread Safety => disabled`	非執行緒安全（`nts` 或 `NTS`）驅動程式檔案
`Architecture => x64`	64 位元驅動程式檔案與 64 位元 ODBC 元件
`Architecture => x86`	32位元 Windows 驅動程式檔案與 32 位元 ODBC 元件

CLI 可以使用執行緒安全或非執行緒安全的 PHP 建置。選擇擴充功能時，請依據報告的值，而不是假設每個 CLI 建置都是非執行緒安全的。

ODBC 驅動程式

在執行 PHP 的電腦上安裝支援的 Microsoft ODBC Driver for SQL Server。從下載適用於 SQL Server 的 ODBC 驅動程式下載驅動程式。

如果您在 64 位元版本的 Windows 上下載 Windows 版本的驅動程式，ODBC 64 位元安裝程式會同時安裝 32 位元和 64 位元的 ODBC 驅動程式。如果您使用 32 位元版本的 Windows，請使用 ODBC x86 安裝程式。在非 Windows 平台上，只有 64 位元版本的驅動程式可供使用。

表格包含用於升級規劃的過往組合。使用目前的 PHP 驅動版本及其列出的 ODBC 版本來進行新安裝。與舊版本相容並不會延長其支援週期。請檢查 PHP 驅動程式的支援生命週期以及 PHP 支援的版本。

空白儲存格並不代表 PHP 驅動程式一定會拒絕該 ODBC 版本。個別功能可能需要比基礎組合更新的 ODBC 版本。

PHP 驅動程式版本 → ↓ ODBC 驅動程式版本	5.13	5.12	5.11	5.10	5.9	5.8	5.6	5.3	5.2	4.3	4.0	3.2
ODBC 驅動程式 18	Yes	Yes	Yes	Yes
ODBC 驅動程式 17	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
ODBC 驅動程式 13.1		Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
ODBC 驅動程式 13											Yes
ODBC 驅動程式 11						Yes	Yes	Yes	Yes	Yes	Yes	Yes

如果您使用 SQLSRV 驅動程式，sqlsrv_client_info 會傳回 Microsoft Drivers for PHP for SQL Server 使用的 SQL Server Microsoft ODBC Driver for SQL Server 版本相關資訊。如果您使用 PDO_SQLSRV 驅動程式，您可以使用 PDO::getAttribute 來探索版本。

SQL Server

有關支援的 SQL Server 版本，請參見支援的資料庫版本。

分別評估 SQL Server、Azure SQL Database、Azure SQL 受控執行個體、Azure Synapse Analytics、Microsoft Fabric 中的 SQL 資料庫，以及 Microsoft Fabric 中的 Warehouse 的目標支援。安裝需求是用戶端需求，並不表示並非每個目標都提供所有認證方法、連線選項、Transact-SQL（T-SQL）功能或資料型態。根據你的應用程式所使用的情境，使用支援矩陣和目標產品的文件。

作業系統

關於支援的作業系統，請參見支援作業系統。

驅動程式版本

每個版本的適用於 SQL Server 的 Microsoft PHP 驅動程式皆附帶 SQLSRV 及 PDO_SQLSRV 驅動程式檔案，提供執行緒安全與非執行緒安全版本。在 Windows 上，每個變體也有提供 32 位元和 64 位元 PHP 版本。請將驅動程式檔案與你的 PHP 版本、執行緒安全模式及架構相匹配。下載驅動程式後啟用驅動程式檔案，請參見「載入 Microsoft PHP 驅動程式 for SQL Server」。

在 Linux 和 macOS 上，請依照 Linux 和 macOS 安裝說明，使用 PIE（PHP 擴充安裝程式）安裝驅動程式。 PIE 取代了已棄用的 PHP 擴充社群函式庫（PECL）套件系統，並將已安裝的擴充套件命名為 sqlsrv.so 或 pdo_sqlsrv.so。以下表格列出你從 Microsoft Drivers for PHP for SQL Server 發行版本頁面手動下載的預建二進位套件檔名。

以下表格列出了 5.13 版本套件中的檔案。在檔名中， ts 和 TS 代表的是執行緒安全， nts 和 NTS 則是非執行緒安全。

Windows 驅動程式檔案

套件包含 Windows_5.13.xRTW.zip 這些檔案。

SQLSRV 檔案	PDO_SQLSRV檔案	PHP 版本	具備執行緒安全性？	Architecture
`php_sqlsrv_83_nts_x86.dll`	`php_pdo_sqlsrv_83_nts_x86.dll`	8.3	否	32-bit
`php_sqlsrv_83_ts_x86.dll`	`php_pdo_sqlsrv_83_ts_x86.dll`	8.3	是	32-bit
`php_sqlsrv_83_nts_x64.dll`	`php_pdo_sqlsrv_83_nts_x64.dll`	8.3	否	64-bit
`php_sqlsrv_83_ts_x64.dll`	`php_pdo_sqlsrv_83_ts_x64.dll`	8.3	是	64-bit
`php_sqlsrv_84_nts_x86.dll`	`php_pdo_sqlsrv_84_nts_x86.dll`	8.4	否	32-bit
`php_sqlsrv_84_ts_x86.dll`	`php_pdo_sqlsrv_84_ts_x86.dll`	8.4	是	32-bit
`php_sqlsrv_84_nts_x64.dll`	`php_pdo_sqlsrv_84_nts_x64.dll`	8.4	否	64-bit
`php_sqlsrv_84_ts_x64.dll`	`php_pdo_sqlsrv_84_ts_x64.dll`	8.4	是	64-bit
`php_sqlsrv_85_nts_x86.dll`	`php_pdo_sqlsrv_85_nts_x86.dll`	8.5	否	32-bit
`php_sqlsrv_85_ts_x86.dll`	`php_pdo_sqlsrv_85_ts_x86.dll`	8.5	是	32-bit
`php_sqlsrv_85_nts_x64.dll`	`php_pdo_sqlsrv_85_nts_x64.dll`	8.5	否	64-bit
`php_sqlsrv_85_ts_x64.dll`	`php_pdo_sqlsrv_85_ts_x64.dll`	8.5	是	64-bit

使用非執行緒安全的驅動程式檔案搭配非執行緒安全的 PHP 編譯，以及使用執行緒安全的驅動程式檔案搭配執行緒安全的 PHP 建置。命令列介面（CLI）可使用任一建置版本。要確認你用的是哪個版本，可以執行 php -i 並檢查 Thread Safety 值。

Linux 與 macOS 驅動程式檔案

Linux_5.13.xRTW.tar.gz和 Mac_5.13.xRTW.tar.gz 套件包含這些檔案。 Linux 壓縮檔包含 x64 二進位檔，macOS 壓縮檔則包含 Arm64 二進位檔。

預建檔案也必須與作業系統的原生函式庫相符。 Linux 5.13.3 的二進位檔需要 glibc 2.38 及更新版本，以及提供 GLIBCXX_3.4.32 的 C++ 執行階段。 macOS 5.13.3 的二進位檔宣告 macOS 26 為其最低部署目標。這些二進位需求與作業系統對原始碼建置的支援是分開的。

當壓縮檔的架構或原生函式庫需求與你的 PHP 安裝不符時，請使用 PIE。為已安裝的 PHP 及原生函式庫提供 PIE 建置版本。不要手動替換系統函式庫來載入預建擴充功能。

SQLSRV 檔案	PDO_SQLSRV檔案	PHP 版本	具備執行緒安全性？
`SQLSRV_8.3_NTS.so`	`PDO_SQLSRV_8.3_NTS.so`	8.3	否
`SQLSRV_8.3_TS.so`	`PDO_SQLSRV_8.3_TS.so`	8.3	是
`SQLSRV_8.4_NTS.so`	`PDO_SQLSRV_8.4_NTS.so`	8.4	否
`SQLSRV_8.4_TS.so`	`PDO_SQLSRV_8.4_TS.so`	8.4	是
`SQLSRV_8.5_NTS.so`	`PDO_SQLSRV_8.5_NTS.so`	8.5	否
`SQLSRV_8.5_TS.so`	`PDO_SQLSRV_8.5_TS.so`	8.5	是

把你需要的每個檔案複製到你的 PHP 擴充套件目錄。你可以保留套件檔名並寫入 extension=SQLSRV_8.4_NTS.so，或將檔案改名為 sqlsrv.so，然後寫成簡短表單 extension=sqlsrv。同樣的命名選擇也套用到PDO_SQLSRV。要找到擴充功能目錄，請執行 php -i | grep extension_dir. 請在 Linux 和 macOS 上依照「載入驅動程式」，在正確的設定檔中啟用擴充功能，並在 PDO_SQLSRV 前載入 PHP 資料物件（PDO）。

早期版本

對於 5.13 之前版本中包含的驅動程式檔案，請從 Microsoft Drivers for PHP for SQL Server 發佈頁面下載該版本的套件並列出其內容。 5.12 之前的版本會為每個作業系統和 PHP 版本發布獨立的套件，而非每個平台的單一套件。

驗證所選環境

安裝 PHP 擴充功能和 ODBC 驅動程式後，但在設定網頁伺服器之前，先執行以下檢查：

php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv

最後兩個指令必須顯示獨立的模組資訊區塊。如果任一指令都報告擴充功能不存在，請先完成平台安裝與載入程序，再測試資料庫連線。

建立 verify-php-drivers.php 以檢查兩個 PHP API 而不要求憑證：

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not loaded.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not loaded.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

用為應用程式提供服務的 PHP 執行檔來執行它：

php verify-php-drivers.php

預期產出：

SQLSRV and PDO_SQLSRV are loaded.

此檢查用以驗證擴充載入。它不會驗證 ODBC 連線、認證、憑證信任、網路存取或資料庫權限。

記錄結果後刪除 verify-php-drivers.php 。

診斷需求失敗

徵兆	可能的擁有人	支票
`PHP Startup: Unable to load dynamic library`	PHP 執行階段或擴充功能選擇	PHP 小版本、架構、執行緒安全模式， `extension_dir`以及精確的檔案名稱
`Call to undefined function sqlsrv_connect()`	SQLSRV 延伸模組設定	`php --ri sqlsrv`、使用中的`php.ini`檔案，以及已掃描的`.ini`檔案
`PDOException: could not find driver`	PDO_SQLSRV 擴充功能或 PDO 擴充功能載入順序	`php --ri pdo_sqlsrv`，`PDO::getAvailableDrivers()`，以及 PDO 是否先載入
缺少 `msodbcsql` 或 `libodbc` 程式庫	ODBC 安裝或作業系統載入器	已安裝 ODBC 套件、架構與共享函式庫相依性
CLI 成功了，但網站卻失敗了	SAPI 專屬的 PHP 設定	比較在`php --ini`後的臨時`phpinfo()`頁面
擴充功能已載入，但連線失敗	ODBC、網路、認證、憑證或資料庫目標	擷取 SQLSRV 錯誤集合或 PDO 例外，並排查報告的 SQLSTATE

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-11-05