安裝 Microsoft Drivers for PHP for SQL Server 驅動程式

SQLSRV 和 PDO_SQLSRV 驅動程式都是 PHP 擴充套件。 PHP 會在 PHP 程序啟動時，讀取 php.ini 與其他額外的 .ini 檔案來載入它們。

載入和安裝是分開的。複製或建置擴充功能會將檔案放到磁碟上。 PHP 無法使用 SQLSRV 或 PDO_SQLSRV，除非目前使用中的設定包含正確條目且 PHP 程序重新啟動。

保護網頁診斷頁面

在建立臨時 phpinfo() 頁面前，請設定網頁伺服器只允許來自 localhost 的請求，或只允許已驗證的管理員存取。這個限制要維持，直到你刪除頁面為止。 phpinfo() 可能暴露環境變數、憑證及伺服器設定。驗證後立即移除該頁面。

了解 PHP 設定的作用範圍

每個 PHP 伺服器應用程式介面（SAPI）可使用不同的執行檔與設定：

Runtime	典型配置來源	如何辨識
命令列介面（CLI）	`php --ini` 回報的 `php.ini` 與掃描目錄	以完全相同的執行檔執行 `php --ini`
IIS FastCGI	在 IIS FastCGI 應用程式中配置的 PHP 執行檔	使用臨時 `phpinfo()` 頁面
Apache 模組	Apache 的 PHP 模組配置	使用臨時 `phpinfo()` 頁面
PHP-FPM	FPM 可執行檔、池、`php.ini` 與掃描目錄	使用 `-i` 執行版本化的 FPM 二進位檔，或使用暫時性的 `phpinfo()` 頁面
長時間執行的背景工作程序	啟動工作者的執行檔與環境	檢查背景工作服務，並在更改後重新啟動

更改 CLI 設定不會改變 IIS、Apache 或 PHP-FPM，當它們使用其他 PHP 安裝或掃描目錄時。

尋找 PHP 設定

請用你應用程式使用的 PHP 執行檔執行以下指令：

php --ini
php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir"

在 Linux 或 macOS 上，請替換 findstr 為 grep：

php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"

「file」命令用來識別所選執行檔的架構。對於通用 macOS 執行檔，請依照明確選擇架構。

載入的設定檔 與 掃描其他 .ini 檔案的位置 的值可識別命令列程序所使用的組態。網頁伺服器或 PHP FastCGI 流程管理器（PHP-FPM）程序可能會使用不同的 PHP 執行檔或設定檔。使用暫存 phpinfo() 頁面來識別該程序的值。

編輯檔案前，請記錄：

PHP 執行檔路徑與版本。
已載入的 php.ini。
附加的 .ini 掃描目錄。
擴充功能目錄。
執行緒安全模式與架構。
每個必須重新啟動的流程。

備份你更改的每個設定檔。

在 Windows 上載入驅動程式

若要安裝 PHP 擴充套件安裝程式（PIE），請先下載並驗證 PIE。從包含 pie.phar 的目錄執行以下指令，並使用將會載入這些驅動程式的 PHP 執行檔：

php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

PIE 安裝 php_sqlsrv.dll 和 php_pdo_sqlsrv.dll。如果 PIE 無法自動啟用擴充功能，請從目前使用中的 php.ini 中移除所有現有的 SQLSRV 和 PDO_SQLSRV 項目，然後新增：

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

每位駕駛者只輸入一個紀錄。更改設定後重新啟動 PHP 程序。

對於 ZIP 安裝，將與 PHP 小版本、架構及執行緒安全模式相符的動態連結函式庫（DLL）複製到 extension_dir 目錄中。 PHP 8.5 x64 執行緒安全執行環境使用以下檔名：

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

在供 PHP 程序使用的 php.ini 中加入兩個檔名：

extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

將 ts、x64 和 85 替換為你的 PHP 執行時值。不要混用安全執行緒與非執行緒安全檔案、32位元與64位元檔案，或是為其他PHP小版本所編譯的檔案。

在 Linux 和 macOS 上安裝驅動程式

用 PIE 安裝驅動程式。更多資訊請參閱 Linux 與 macOS 安裝教學。 PIE 安裝副檔名檔案，並嘗試透過平台的 PHP 設定工具，或在額外的 php.ini PHP 設定檔或標準 .ini 中新增一個 extension= 項目來啟用它們。如果 PIE 回報無法啟用擴充功能，請自行新增條目並驗證目前作用中的組態。

手動安裝時，請選擇與你的 PHP 版本、架構、執行緒安全模式及作業系統原生函式庫相符的預建 .so 檔案。檢查 Linux 和 macOS 的預先建置需求；如果環境不符，就使用 PIE。

例如，PHP 8.4 非執行緒安全的檔案命名為 SQLSRV_8.4_NTS.so 和 PDO_SQLSRV_8.4_NTS.so。將它們放入由 php -i | grep extension_dir 傳回的目錄中。將它們重新命名為 sqlsrv.so 和 pdo_sqlsrv.so 以使用以下條目，或改用條目中完全相同的套件檔名。依本節所述的載入順序，將這些條目加入你目前使用中的 PHP 設定：

extension=sqlsrv.so
extension=pdo_sqlsrv.so

PHP 資料物件（PDO）必須在PDO_SQLSRV前載入。 PHP 會先讀取 php.ini，再掃描其他 .ini 檔案，依字母順序排列。如果你的發行版從掃描的檔案載入 pdo.so，請將 PDO_SQLSRV 條目放入後續掃描的檔案中，例如當 PDO 使用 10-pdo.ini 時，使用 30-pdo_sqlsrv.ini。那就不要把PDO_SQLSRV條目放進 php.ini 去。

選擇擴充項目

請使用與驅動程式安裝方式相符的條目：

平台與方法	SQLSRV 條目	PDO_SQLSRV 項目
搭載 PIE 的 Windows	`extension=php_sqlsrv.dll`	`extension=php_pdo_sqlsrv.dll`
Windows 已解壓縮的 ZIP	精確版本的 DLL 名稱，例如 `extension=php_sqlsrv_85_ts_x64.dll`	精確版本的 DLL 名稱，例如 `extension=php_pdo_sqlsrv_85_ts_x64.dll`
Linux 或 macOS 搭配 PIE	`extension=sqlsrv.so`	`extension=pdo_sqlsrv.so`
Linux 或 macOS 已解壓縮的封存檔，並重新命名檔案	`extension=sqlsrv.so`	`extension=pdo_sqlsrv.so`
Linux 或 macOS 發布的封存檔、原始檔案	精確的封存檔名，例如 `extension=SQLSRV_8.4_NTS.so`	確切的封存檔案名稱，例如 `extension=PDO_SQLSRV_8.4_NTS.so`

不要同時設定短名稱和版本化名稱，針對同一擴充功能。 PHP 可以回報某個模組已經載入，或在升級後繼續載入舊檔案。

重新啟動 PHP 以載入驅動程式

更改副檔名或設定檔後，重新啟動該程序。重新啟動網頁伺服器、PHP-FPM、佇列工作者及其他會載入驅動程式的長時間執行 PHP 程序。

SQLSRV 和 PDO_SQLSRV 擴充功能可以獨立載入，但當應用程式同時使用兩個驅動程式時，請同時安裝並驗證兩者。 PDO 內建在許多 PHP 套件中。如果 PDO 沒有內建，請在PDO_SQLSRV前啟用 PDO 擴充功能。

驗證已載入的驅動程式

若使用命令列執行，請執行：

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"

在 Linux 或 macOS 上，請使用：

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

對於網頁伺服器，在建立包含的臨時頁面前，先<?php phpinfo(); ?>。確認 已載入的設定檔、extension_dir，以及獨立的 sqlsrv 和 pdo_sqlsrv 區塊。驗證後移除該頁面。

也要執行 PHP 層級的檢查，確保驗證涵蓋兩個 API，而不只是模組名稱。將此程式儲存為 verify-php-drivers.php：

<?php
$checks = [
    'SQLSRV extension' => extension_loaded('sqlsrv'),
    'SQLSRV API' => function_exists('sqlsrv_connect'),
    'PDO_SQLSRV extension' => extension_loaded('pdo_sqlsrv'),
    'PDO_SQLSRV API' => class_exists('PDO')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $passed) {
    echo $name . ': ' . ($passed ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$passed;
}

exit($failed ? 1 : 0);

執行該程式時，搭配你的應用程式所使用的每個 PHP 執行檔：

php verify-php-drivers.php

預期產出：

SQLSRV extension: loaded
SQLSRV API: loaded
PDO_SQLSRV extension: loaded
PDO_SQLSRV API: loaded

對於網頁執行時，暫時將檔案放在文件根目錄中，並在瀏覽器中存取該檔案。驗證後移除。這個程式不會開啟資料庫連線或列印設定值。

完成 CLI 和網頁執行時檢查後刪除 verify-php-drivers.php 。

疑難排解驅動程式載入問題

徵兆	檢查原因	糾正措施
`Unable to load dynamic library`	錯誤的檔名、 `extension_dir`PHP 小版本、架構或執行緒安全模式	將其與所選驅動程式檔案比較`php -i`，並暫時使用絕對路徑來隔離路徑錯誤
`The specified module could not be found` 在 Windows 上	驅動程式 DLL 或其相依項目無法取得	確認 DLL 位於 `extension_dir` 中，安裝對應的 Visual C++ 執行環境，並檢查任何仍遺失的 DLL 相依性
`undefined symbol` 或在 Linux 或 macOS 上出現共享函式庫錯誤	擴充套件與 PHP 建置不符，或缺少 ODBC 依賴	使用預期的 `php-config` 重新建置，然後檢查報告遺失的函式庫
`Module "sqlsrv" is already loaded`	重複項目或兩個掃描檔案	搜尋已載入的 `php.ini` 和掃描目錄，然後保留一個條目
`could not find driver` 來自PDO	PDO_SQLSRV 沒有載入，或者 PDO 在它之後才載入	檢查 `php --ri pdo_sqlsrv` 並將 PDO_SQLSRV 條目移至 PDO 之後
CLI 是可以運作的，但網頁請求會失敗	不同的 SAPI 設定或是未重新啟動的處理程序	比較 CLI 與 `phpinfo()` 設定值，編輯網頁設定，並重新啟動網頁程序
升級後仍保留舊的 `ExtensionVer`	設定仍使用較舊版本的檔名	將舊條目替換為所選方法安裝的檔案，移除重複資料，並重新啟動所有 PHP 程序

PHP 負責擴充套件探索與載入順序。 PIE 或手動複製會提供擴充功能檔案。作業系統載入器則解析原生相依性。擴充功能載入後，Microsoft ODBC 驅動程式會接管資料庫通訊協定。

意見反應

此頁面對您有幫助嗎？

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