前言

"装好了 PHP 8.1，但就是不生效"是一句有歧义的话。它可能指三种情况：命令行的php -v还是旧版本；浏览器里的phpinfo()还是旧版本；或者版本号对了，但某个新语法、某个扩展就是不能用。三者原因完全不同，混在一起排查就是在原地打转。

更麻烦的是，PHP 的"生效"取决于四个互相独立的环节：命令行的PATH顺序、Web 服务器指向的处理器（Apache 的模块、Nginx 转发的 FastCGI 端口、IIS 的处理程序映射）、php.ini的实际加载路径，以及 OPcache 与正在跑的服务进程有没有重启。任何一环没对上，别处做的努力都是白费。

本文按"先定位在哪一层 → 逐层排查"的顺序讲，并给出一个能一次打印出全部事实的探测脚本。PHP 8.1 带来的枚举（enum）、readonly属性、never返回类型、纯交叉类型等语法，会在最后一节用来验证"到底生效了没有"。

一、先把"不生效"拆成一个可以回答的问题

先对着下面这张表定位你看到的现象属于哪一种，答案就在对的列里。

把现象归到这几行里的任意一行，后面的排查就变成逐条命令确认。

二、探测脚本：一次把全部事实打印出来

先把这个脚本放到站点目录下访问一次，它会把互相纠缠的事实分开打印。需要 PHP 7.0+（不依赖 8.1 语法，可以在旧版本上跑起来做对比）。

<?php declare(strict_types=1); // probe.php —— 临时探测脚本，用完删除 header('Content-Type: text/plain; charset=utf-8'); echo '=== 身份 ===', PHP_EOL; echo 'PHP_VERSION : ', PHP_VERSION, PHP_EOL; echo 'PHP_SAPI : ', PHP_SAPI, PHP_EOL; echo 'PHP_INT_SIZE : ', PHP_INT_SIZE, ' 字节（4 = 32 位，8 = 64 位）', PHP_EOL; echo PHP_EOL; echo '=== ini 文件 ===', PHP_EOL; echo 'loaded ini : ', (php_ini_loaded_file() ?: '(none，说明没加载任何 php.ini)'), PHP_EOL; $scanned = php_ini_scanned_files(); echo 'scanned ini : ', ($scanned === false || $scanned === '' ? '(none)' : $scanned), PHP_EOL; echo 'extension_dir : ', (ini_get('extension_dir') ?: '(空)'), PHP_EOL; echo 'open_basedir : ', (ini_get('open_basedir') ?: '(off)'), PHP_EOL; echo PHP_EOL; echo '=== OPcache 运行时状态 ===', PHP_EOL; if (function_exists('opcache_get_status') && is_array($status = opcache_get_status(false))) { echo 'opcache 已启用 : ', (($status['opcache_enabled'] ?? false) ? '是' : '否'), PHP_EOL; echo '缓存的脚本数 : ', (string) ($status['opcache_statistics']['num_cached_scripts'] ?? '未知'), PHP_EOL; echo 'validate_timestamps : ', ini_get('opcache.validate_timestamps'), PHP_EOL; } else { echo 'opcache 未启用或扩展未加载', PHP_EOL; } echo PHP_EOL; echo '=== 扩展 ===', PHP_EOL; $check = [ 'pdo_mysql', 'mysqli', 'mbstring', 'curl', 'openssl', 'fileinfo', 'bcmath', 'dom', 'tokenizer', 'xml', 'zip', 'intl', 'gd', 'redis', ]; foreach ($check as $ext) { echo str_pad($ext, 30), ': ', (extension_loaded($ext) ? '已加载' : '未加载'), PHP_EOL; } echo PHP_EOL; echo '=== PHP 8.1 特性可用性 ===', PHP_EOL; // enum_exists() 是 PHP 8.1 新增的函数，8.0 及以下不存在 echo 'enum_exists() : ', (function_exists('enum_exists') ? '可用（>= 8.1）' : '不可用（< 8.1）'), PHP_EOL; echo 'array_is_list() : ', (function_exists('array_is_list') ? '可用（>= 8.1）' : '不可用（< 8.1）'), PHP_EOL; echo 'Fiber 类 : ', (class_exists('Fiber') ? '可用（>= 8.1）' : '不可用（< 8.1）'), PHP_EOL; echo 'fsync() : ', (function_exists('fsync') ? '可用（>= 8.1）' : '不可用（< 8.1）'), PHP_EOL;

访问方式建议用curl而不是浏览器，绕开浏览器缓存和 CDN 的干扰：

curl -s http://blog.test/probe.php

看三个地方就够了：PHP_VERSION是不是 8.1、loaded ini是不是你改的那一份、PHP 8.1 特性可用性四行是不是都"可用"。三个都对，说明这个 SAPI 上的 PHP 8.1 确实生效了。

三、CLI 侧：PATH 里到底有几个 php

命令行不生效，九成是PATH里躺着一个更靠前的旧版本。

# Windows：列出 PATH 中所有能命中的 php， # 第一个就是最终被执行的 where php # Linux / macOS which -a php # 看真实版本和真实 ini php -v php --ini php -i | grep -i "loaded configuration"

Windows 上常见的情况是同时装了 PhpStudy、XAMPP、WAMP，或者用 Chocolatey 装过一个，几个php.exe全在PATH里，谁排前面谁赢。Linux 上用sudo update-alternatives --config php统一切换。

这里有一条必须点明的分界线：Composer 用的是 CLI 的 PHP。在面板里把站点切到 8.1，而php -v还是 7.4，composer install依然会按 7.4 去解析依赖。这两件事互不影响。

要让命令行用的确定是 8.1，最稳的不是去调PATH，而是显式指定解释器：

D:/phpstudy_pro/Extensions/php/php8.1.27nts/php.exe -v # 用指定版本跑 Composer D:/phpstudy_pro/Extensions/php/php8.1.27nts/php.exe \ D:/phpstudy_pro/Extensions/composer/composer.phar install

四、Web 侧：三条技术路线，各有各的检查点

Web 侧的 PHP 由服务器怎么"接上" PHP 决定，三条路线的排查点完全不同。

Apache用httpd -M列出已加载的模块，看 PHP 那一行是不是你期望的版本对应的模块文件。这里有个容易踩的硬约束：Apache 用的php8apache2_4.dll必须是Thread Safe（TS）构建，且编译器版本和架构（x64 / x86）要和 Apache 本体匹配。用 NTS 构建的 DLL 配 Apache 模块，Apache 会直接起不来；而 FastCGI / CGI 方式则常用 NTS 构建。

Nginx不直接加载 PHP，它把请求转发给一个 FastCGI 进程。所以"版本不生效"在这里的正确表现是：fastcgi_pass指向的端口后面，跑的是旧版本的 PHP-FPM 或 php-cgi。

# Linux：看端口是谁在监听 netstat -tlnp | grep 9000 # Windows netstat -ano | findstr :9000 tasklist /FI "PID eq 1234"

如果端口上跑的确实是旧版本，要改的是"谁的进程占着这个端口"，而不是php.ini。反过来，如果端口根本没人监听，症状是 502 而不是版本不对——这两个现象不要混为一谈。

IIS的检查点在"处理程序映射"和"FastCGI 设置"里，两者都要指向 8.1 目录下的可执行文件。只改一处会出现"映射是新的、FastCGI 环境变量还是旧的"这种半生效状态。

五、php.ini到底加载了哪一个

这是最容易被误判的一层。php -i输出里的Loaded Configuration File才是唯一事实，别凭目录猜。

(none)这一条尤其值得警惕：PHP 在没有任何php.ini的情况下依然能正常启动、能执行脚本、能打印版本号，只是所有扩展都是未加载状态。所以你会看到"版本对了但pdo_mysql用不了"这种看似矛盾的现象。

# 交叉验证：ini 路径 + 已加载扩展 + 有没有环境变量在覆盖 ini 位置 php --ini php -m set PHPRC # Windows echo "$PHP_INI_SCAN_DIR" # Linux / macOS

六、扩展没生效：extension_dir是关键

改完php.ini打开了扩展，重启后php -m里还是没有，绝大多数情况是extension_dir指错了目录。

; Windows 示例：路径用正斜杠或双反斜杠 extension_dir = "D:/phpstudy_pro/Extensions/php/php8.1.27nts/ext" extension=pdo_mysql extension=mbstring extension=curl extension=openssl

排查顺序是：php -i | grep extension_dir看实际值，再去那个目录里看有没有对应的文件（Windows 上是带php_前缀的php_pdo_mysql.dll，Linux 上通常是pdo_mysql.so）。目录里没有 = 装错了；目录里有但没加载 = 配置行没生效。Linux 下用发行版包管理器装的 PHP，扩展是独立的包，要单独装。

七、OPcache 与服务重启：最容易被漏掉的一层

前面几层都对，页面还是老的，那就是进程或缓存的问题。

# Linux：重启 FPM 与 Web 服务器 sudo systemctl restart php8.1-fpm sudo systemctl restart nginx # 或者只让 FPM 平滑重载（不打断正在处理的请求） sudo kill -USR2 "$(cat /run/php-fpm/php-fpm.pid)"

Windows 下通过面板或服务管理器重启。注意：只重启 PHP 服务不够，Nginx / Apache 也可能缓存了到后端的连接。

OPcache 是另一条独立线索。它缓存的是编译后的字节码，不是版本号，所以它不会让"版本切换"失效，但会让"改了代码不生效"：

; 开发环境务必这样设，否则每次改代码都要重启 opcache.enable = 1 opcache.validate_timestamps = 1 opcache.revalidate_freq = 0

如果validate_timestamps是0，PHP 永远不会去检查源文件有没有变，改动要等到进程重启才生效——这会让人误以为"换了 PHP 版本还是老行为"。临时清一下缓存：

<?php // 需要 PHP 5.5+（opcache_reset 自 PHP 5.5 起可用） if (function_exists('opcache_reset')) { var_dump(opcache_reset()); }

实战：用 8.1 的语法验证版本真的生效了

版本号可以撒谎（比如某个中间层做了替换），语法不会。下面这段代码只使用 PHP 8.1 引入的特性，在 8.0 及以下会因为语法错误或未定义函数直接失败。需要 PHP 8.1+：

<?php declare(strict_types=1); // verify81.php —— 需要 PHP 8.1+ // —— 1. 枚举（enum），PHP 8.1 新增 —— enum Status: string { case Draft = 'draft'; case Published = 'published'; case Archived = 'archived'; public function label(): string { return match ($this) { Status::Draft => '草稿', Status::Published => '已发布', Status::Archived => '已归档', }; } } echo Status::Published->label(), PHP_EOL; // 已发布 echo Status::from('draft')->name, PHP_EOL; // Draft // —— 2. readonly 属性，PHP 8.1 新增 —— final class Money { public function __construct( public readonly string $currency, public readonly int $amountInCents, ) { } } $price = new Money('CNY', 1999); printf("%s %.2f\n", $price->currency, $price->amountInCents / 100); // CNY 19.99 // —— 3. never 返回类型，PHP 8.1 新增 —— function fail(string $message): never { throw new RuntimeException($message); } // —— 4. 纯交叉类型（pure intersection type），PHP 8.1 新增 —— interface HasCount { public function count(): int; } interface HasLabel { public function label(): string; } // 参数必须同时满足两个接口，注意这里只能是接口，不能是类。 // 光是能声明出来，就证明解析器接受了这套 8.1 语法。 function describe(HasCount&HasLabel $value): string { return $value->label() . '（' . $value->count() . ' 项）'; } // —— 5. array_is_list()，PHP 8.1 新增 —— var_dump(array_is_list([1, 2, 3])); // true var_dump(array_is_list([1 => 'a', 0 => 'b'])); // false // —— 6. 第一类可调用语法（first-class callable），PHP 8.1 新增 —— $lengths = array_map(strlen(...), ['a', 'bb', 'ccc']); print_r($lengths); // —— 7. new 出现在初始化器里，PHP 8.1 新增 —— class NullLogger { public function __toString(): string { return 'NullLogger'; } } // 默认参数值可以直接 new 一个对象（PHP 8.1 之前只允许常量表达式） function makeLogger(object $logger = new NullLogger()): string { return (string) $logger; } echo makeLogger(), PHP_EOL; // NullLogger echo 'PHP ', PHP_VERSION, ' 的 8.1 特性全部可用', PHP_EOL;

这个脚本能跑通，说明执行它的那个 PHP 确实在 8.1 或更高版本上，没有中间层在骗你。

常见坑点

坑 1：php.ini在 Windows 上其实是php.ini.txt

❌ 记事本保存时"另存为文本文件"，文件名变成php.ini.txt，资源管理器默认隐藏扩展名，看起来完全正常

✅ 打开"显示文件扩展名"确认，或者直接看 PHP 怎么说的：

php --ini php -i | grep -i "loaded configuration"

如果输出是(none)，而你坚信自己改过php.ini，八成就是这个原因。

坑 2：改的是php.ini-development或php.ini-production

❌ 目录里有三个文件，编辑了php.ini-development，重启后毫无变化

✅ 先php --ini看实际加载的是哪个文件名，再改那一个

坑 3：Loaded Configuration File是(none)，但 PHP 照样跑

❌ 看到php -v能输出、脚本能执行，就认为配置没问题

✅ 没有php.ini时 PHP 用内置默认值运行，所有扩展都不加载。php -m里缺东西就要查这里

坑 4：Apache 用了 NTS 构建的 DLL

❌ 把php8apache2_4.dll配好，Apache 启动失败或模块加载报错

✅ Apache 模块方式必须用Thread Safe（TS）构建，且架构（x64 / x86）和编译器版本要与 Apache 本体匹配。FastCGI 方式才常用 NTS

坑 5：Nginx 报 502，却跑去改php.ini

❌ 站点 502 Bad Gateway，第一反应是去调 PHP 配置

✅ 502 的含义是"连不上后端进程"。用netstat -tlnp | grep 9000确认fastcgi_pass指向的端口有没有进程在听

坑 6：只重启了 PHP 服务，没重启 Web 服务器

❌ 只重启 PHP-FPM，Nginx 仍然连着旧的 FastCGI 连接

✅ Web 服务器和 PHP 服务一起重启；或至少让 FPM 平滑重载

坑 7：CLI 与 Web 加载不同的php.ini，只改了一个

❌ 在命令行php -m里看到pdo_mysql已加载，就以为站点也没问题

✅ 两个 SAPI 各查一次，用探测脚本在浏览器里再确认一遍

总结

排查"不生效"的核心方法是先定位再动手：用探测脚本把版本、SAPI、ini 路径、扩展状态一次性打印出来，问题会自己浮到水面上。最耗时间的做法是凭直觉改配置——改错文件、改错 SAPI、忘了重启，这三种情况占了绝大多数。