phpEnv下安装SQL Server驱动(sqlsrv)实战

phpEnv下安装SQL Server驱动(sqlsrv)实战

在phpEnv环境下安装sqlsrv扩展失败，十有八九是踩了“三位一体”的坑：扩展文件、PHP运行时本身以及系统ODBC驱动，这三者没有严丝合缝地对上号。问题往往不在于“没下载”，而在于“根本没匹配上”。

确认 phpEnv 的 PHP 架构和线程模型

第一步，得先摸清自家“地基”的情况。phpEnv默认打包的PHP版本多为NTS（非线程安全）和x64架构，但如果你用的是旧版本或自定义安装包，情况可能就不同了，可能是TS（线程安全）或x86架构。一旦错配，php_sqlsrv_*.dll这个扩展就加载不起来，而且php -m命令可能还不报错，用extension_loaded('sqlsrv')检查也只会返回false，让人一头雾水。

• 打开终端，先执行php -v确认PHP具体版本（例如8.1.22）。
• 接着，执行php -i | findstr "Architecture Thread"（Windows系统）或php -i | grep -E "(Architecture|Thread)"（Linux/macOS系统）。关键要看输出里是否包含x64和NTS。
• 如果显示的是TS，就必须使用带_ts.dll后缀的扩展文件；如果显示x86，那就绝对不能使用带_x64后缀的DLL。

下载并启用正确的 sqlsrv 扩展 DLL

微软官方已经不再为phpEnv这类集成环境提供单独的扩展包了，所以我们必须手动去官网“对号入座”。截至2026年，最新的稳定版是SQLSRV 5.11，支持PHP 8.0到8.3。

• 访问微软官方PHP驱动下载页面，找到与你PHP版本、架构、线程模型完全匹配的包，比如php_sqlsrv_81_nts_x64.zip。
• 解压下载的ZIP文件，将其中的php_sqlsrv_81_nts_x64.dll和php_pdo_sqlsrv_81_nts_x64.dll两个文件，复制到phpEnv对应PHP版本的ext/目录下（路径类似phpenv/php/php-8.1.22/ext/）。
• 然后，编辑该PHP版本目录下的php.ini文件（通常在phpenv/php/php-8.1.22/conf/php.ini），在文件末尾添加两行配置：
  extension=sqlsrv
extension=pdo_sqlsrv
  ⚠️ 注意：这里只需写扩展名，不要写完整的文件路径或.dll后缀，phpEnv会自动识别。

必须安装系统级 ODBC 驱动（Windows）

这是另一个关键点，但常被遗漏。phpEnv自带的PHP并不包含连接SQL Server所需的ODBC驱动。这意味着，即使sqlsrv扩展加载成功，尝试连接数据库时，依然可能遇到Named Pipes Provider: Could not open a connection或TCP Provider: Error code 0x2746这类让人困惑的错误。

立即学习“PHP免费学习笔记（深入）”；

• 前往微软官网，下载并安装“ODBC Driver 18 for SQL Server”的安装程序（.msi文件）。
• 运行安装程序，使用默认路径即可，安装后通常无需重启系统。安装完成后，可以检查C:\Windows\System32\msodbcsql18.dll这个文件是否存在。
• 验证安装：在命令行执行odbcad32打开ODBC数据源管理器，切换到“驱动程序”标签页，确认能看到ODBC Driver 18 for SQL Server这一项。

连接测试时 localhost 比 127.0.0.1 更可靠

到了连接测试这临门一脚，细节决定成败。SQL Server默认启用了命名管道（Named Pipes）连接方式，而在phpEnv环境下，PHP有时会因为TCP/IP协议未启用或被防火墙拦截，导致使用127.0.0.1这个IP地址连接时被拒绝，错误信息可能是Connection refused或Server is not found or not accessible。

• 一个更稳妥的做法是使用localhost代替IP地址进行连接：
  $conn = sqlsrv_connect('localhost', ['Database' => 'testdb', 'Uid' => 'sa', 'PWD' => 'xxx']);
• 如果使用localhost仍然失败，可以打开“SQL Server配置管理器”，依次展开“SQL Server网络配置”，找到你实例的协议，确保TCP/IP和Named Pipes两者都处于“已启用”状态。
• 另外，在连接字符串中，除非你明确禁用了动态端口并只使用固定端口，否则尽量不要硬编码端口号（如localhost,1433）。

最后，还有一个极易被忽略的细节：phpEnv允许你切换不同的PHP版本，而每个版本都有自己独立的php.ini配置文件。你为A版本添加的扩展配置，对B版本是无效的。系统级的ODBC驱动安装一次即可，但sqlsrv的扩展DLL文件，需要为你计划使用的每一个PHP版本都单独放置一份在对应的ext/目录里。