如何解决PHP连接SQL Server时的驱动安装难题_在Linux下部署sqlsrv与pdo_sqlsrv

先说结论——PHP 连 SQL Server 时报 could not find driver，十有八九是 sqlsrv 和 pdo_sqlsrv 这两个扩展没装对，或者底层的 ODBC 驱动压根没装、版本不匹配。这事跟 PHP 版本高不高、低不低关系不大，真正的命门在于三个组件——ODBC 驱动、PHP 扩展、PHP 配置——必须严丝合缝地对齐。哪怕一个环节出了岔子，报错就是它。

为什么 pecl install 会失败或加载不了

pecl install 这条命令看似是一条命令搞定的事，但实际操作中，很多人卡在编译环节过不去。问题根源在于，它依赖系统级的头文件和链接库，而这些恰恰是默认环境里经常没装全的。比如 unixODBC-devel 缺失，phpize 就会直接甩一句“Cannot find header file(s) for sqlsrv”；要是连 gcc 或 make 都没装，configure 那一步根本跑不起来。

所以，在动手之前，先确认这几样东西齐不齐：

• gcc、make 这些基础编译工具
• php-devel（注意要对上你的 PHP 版本，比如 PHP 7.4 就用 php74-devel）
• unixODBC-devel

另外还有两个容易踩的坑。第一个，pecl install sqlsrv 默认装的是最新版，但 PHP 7.4 的环境里，兼容性最稳的反而是 sqlsrv-5.10.1 和 pdo_sqlsrv-5.10.1。新版装上去，搞不好就 segfault 或者 502，得不偿失。第二个，如果你在用宝塔面板，phpize 和 php-config 的路径不是系统默认的，得用宝塔自己的实际路径，比如 /www/server/php/74/bin/phpize。拿错路径，编译第一步就挂了。

ODBC 驱动装哪个版本才不翻车

微软官方提供的 ODBC 驱动有好几个主版本：13.x、17.x、18.x。但这里有个反直觉的事——不是版本越新就越好。SQL Server 2019 及更高版本，官方推荐用 msodbcsql17，这本身没问题。但如果你用的是某些国产 Linux 发行版（比如 openEuler）或者旧内核，17.x 可能会跟 libcrypto 发生符号冲突，后果很严重：PHP-FPM 一启动就直接崩溃。

所以，稳妥点的做法是：

• CentOS 7 / RHEL 7 这类常见环境，优先选择 msodbcsql17，执行 ACCEPT_EULA=Y yum install -y msodbcsql17 就行。
• 要是装完之后 PHP 报 502，或者日志里出现 undefined symbol: OPENSSL_sk_num 这样的字样，别犹豫，立马卸载 17.x，换回 msodbcsql13。13.x 需要手动下载 rpm 包，然后用 yum localinstall 安装。
• 无论装哪个版本，装完之后一定检查一下：cat /etc/odbcinst.ini，看看里面有没有 [ODBC Driver 17 for SQL Server] 这样的条目，以及它指向的 Driver= 路径，对应的 .so 文件是不是真实存在的。这一步经常被跳过，但恰恰是关键。

扩展加载后仍不生效的隐藏原因

有些人卡在这一步：命令行里 php -m | grep sqlsrv 明明能看到扩展，但一到 Web 环境就报错。这种情况，十有八九是 PHP 配置没打到正确的地方，或者被宝塔面板的多版本机制绕过去了。

几个细节值得注意：

• 宝塔 PHP 7.4 的真实配置目录是 /www/server/php/74/etc/php.ini，不是系统默认的 /etc/php.ini。扩展配置建议单独写成文件，放到 /www/server/php/74/etc/php.d/20-sqlsrv.ini 里，这样优先级更可控。
• 扩展的加载顺序也有讲究。pdo_sqlsrv.so 必须在 pdo.so 之后加载，否则 PDO::SQLSRV 的 DSN 会被直接忽略。建议 ini 文件里写成这样：
  extension=pdo.so
extension=sqlsrv.so
extension=pdo_sqlsrv.so
• 最后一步，重启服务必须完整。宝塔环境里要用 systemctl restart php-fpm-74（注意命名规则），光 reload nginx 或者重启面板，很多时候不顶用。

验证是否真成功，别信 phpinfo() 就完事

phpinfo() 里能看到扩展名，只说明它“注册了”，不代表真的能连上 SQL Server。真正有效的验证，是写一段最小化的连接代码，实际跑一遍，并且把异常细节抓出来看。

建议在 Web 目录下放一个 test-sqlsrv.php，内容如下：

getMessage();
}
?>

如果报 SQLSTATE[IMSSP]: This extension requires the Microsoft ODBC Driver for SQL Server，说明 ODBC 驱动的路径没被 PHP 进程读到。这时候需要检查环境变量 LD_LIBRARY_PATH 里是否包含了 /opt/microsoft/msodbcsql17/lib64。如果报 SQLSTATE[08001]: [Microsoft][ODBC Driver 17 for SQL Server]Login timeout expired，反而是好消息——驱动已经顺利加载了，问题出在网络或者认证上，这是正常的排查路径。

还有一个极容易被忽略的细节：宝塔面板的「PHP 设置」页面里有个「禁用函数」列表，如果里面误加了 putenv，会导致 ODBC 驱动无法读取环境变量（比如 ODBCSYSINI），结果就是找不到 odbcinst.ini。这种问题不会报任何扩展相关的错误，只会静默失败，排查起来极其隐蔽。