升级PHP至8.x后PHPUnit类找不到问题求助

升级公司WordPress官网的PHP版本从7.4到8.2后，PHPUnit测试出现错误：

Class phpunit cannot be found in /usr/src/wordpress/wp-content/themes/company-website/vendor/bin/phpunit

但执行./vendor/bin/phpunit --version能正常输出版本信息：

PHPUnit 11.1.3 by Sebastian Bergmann and contributors.

说明Composer已正确安装PHPUnit，但无论是原版本9.6.19还是升级后的11.1.3，均触发该错误。询问PHP8.x是否对PHPUnit的安装/配置有新要求。

PR修改内容（注释行代表被替换的旧内容） #

Dockerfile #

# FROM wordpress:php7.4-apache as wordpress

FROM wordpress:php8.2-apache as wordpress

...
    
# pecl install xdebug-3.1.0 && \

pecl install xdebug-3.3.2 && \

...

# curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer --version=2.2.7

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer --version=2.7.4

drone.Dockerfile #

# FROM wordpress:php7.4-apache as wordpress

FROM wordpress:php8.2-apache as wordpress

...

# curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer --version=2.2.7

curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer --version=2.7.4

docker-compose.yml #

# composer:
#   image: composer:2.2.7

composer:
  image: composer:2.7.4

...

# phpcs:
#   image: php:7.3-cli

phpcs:
  image: php:8.2-cli

...

# phpcbf:
#   image: php:7.3-cli

phpcbf:
  image: php:8.2-cli

composer.json（已同步更新composer.lock） #

// "require-dev": {
//   "phpunit/phpunit": "^9.5",
// }

"require-dev": {
   "phpunit/phpunit": "^11.1",
} 

测试执行脚本run-phpunit.sh #

./vendor/bin/phpunit --version
./vendor/bin/phpunit --no-configuration --coverage-clover coverage/clover.xml --coverage-filter _includes/ --testdox tests

原因及解决方法 #

1. PHPUnit版本与PHP8.x的兼容性细节 #

• PHPUnit 11.x强制要求PHP≥8.2，你当前环境符合要求，但要注意：PHPUnit 9.x仅支持PHP7.4~8.1，在PHP8.2下运行会存在命名空间、类加载的兼容性问题，不建议混用。
• 若要保留PHPUnit 9.x，需将PHP版本降至8.1；若坚持用PHP8.2，必须使用PHPUnit 10.x及以上版本。

2. Composer自动加载器异常 #

PHP8.x对命名空间的解析更严格，若自动加载器未正确生成，会导致找不到类：

• 执行以下命令重新生成自动加载文件：

  composer dump-autoload -o
  

• 检查vendor/bin/phpunit脚本开头的自动加载路径是否正确，正常应为：

  require __DIR__ . '/../autoload.php';
  

  若路径错误，手动修正为项目根目录下的autoload.php相对路径。

3. 脚本执行的工作目录问题 #

如果run-phpunit.sh不是在项目根目录（vendor所在目录）执行，会导致路径错误：

• 在脚本开头添加目录切换命令：

  cd "$(dirname "$0")"
  

• 或直接使用绝对路径执行PHPUnit：

  /usr/src/wordpress/wp-content/themes/company-website/vendor/bin/phpunit [参数]
  

4. PHP配置的路径限制 #

PHP8.x可能开启了open_basedir限制，导致PHPUnit无法读取必要文件：

• 检查php.ini中的open_basedir配置，确保包含项目目录和临时目录：

  open_basedir = /usr/src/wordpress/wp-content/themes/company-website/:/tmp/
  

5. Xdebug干扰 #

Xdebug3.3.2虽兼容PHP8.2，但错误的Xdebug模式可能影响PHPUnit运行：

• 临时关闭Xdebug测试：

  php -d xdebug.mode=off ./vendor/bin/phpunit
  

• 若测试正常，调整Xdebug配置为仅启用覆盖率模式（匹配你的测试需求）：

  xdebug.mode=coverage
  

内容的提问来源于stack exchange，提问作者jsue-vy