迁移Laravel代码库到新开发环境后如何让PHPUnit测试正常运行

1. 检查PHPUnit专属配置覆盖问题 #

• 首先确认项目根目录下的phpunit.xml（或phpunit.xml.dist）文件中的数据库配置，Laravel默认会在运行PHPUnit时优先读取该文件内的环境变量，优先级高于.env文件
• 重点核对以下配置项是否和Ubuntu环境的实际配置匹配：

  <server name="DB_CONNECTION" value="mysql"/>
  <server name="DB_DATABASE" value="你测试库的名称"/>
  <server name="DB_USERNAME" value="测试库有权限的用户名"/>
  <server name="DB_PASSWORD" value="对应用户密码"/>
  

• 如果你之前在WSL环境自定义过phpunit的环境变量，迁移时未同步该文件，就会出现配置不匹配的问题

2. 检查运行环境依赖与权限 #

• 先安装所有PHP扩展依赖，Laravel的PHPUnit运行需要的扩展可能未装全，执行命令：
  sudo apt install php-mysql php-xml php-mbstring php-curl php-zip -y
• 检查项目目录的读写权限，确保当前运行PHPUnit的用户对storage/、bootstrap/cache/目录有读写权限，执行：
  sudo chown -R $USER:$USER /path/to/your/laravel/project
chmod -R 755 storage bootstrap/cache

3. 测试库迁移与配置校验 #

• 运行PHPUnit前需要先执行测试库的迁移，不要直接用生产/开发库的迁移记录，执行命令：
  php artisan migrate --env=testing
• 如果你配置了sqlite作为测试库，需要先安装php-sqlite扩展：
  sudo apt install php-sqlite3 -y

4. 清除旧配置缓存 #

• 迁移项目后很容易残留旧环境的配置缓存，执行以下命令清除所有缓存：

  php artisan config:clear
  php artisan cache:clear
  php artisan route:clear
  php artisan view:clear
  

• 确认清除后再运行./vendor/bin/phpunit测试是否正常

5. 定位具体报错 #

• 执行PHPUnit时加上-v参数输出详细报错：
  ./vendor/bin/phpunit -v
• 常见的报错对应原因：
  • 连接数据库被拒：核对phpunit.xml里的数据库账号密码、端口，确认MySQL服务正常运行systemctl status mysql
  • 表不存在：未执行测试库迁移，或者phpunit配置的数据库名错误
  • 权限错误：目录权限不足，或者PHP扩展缺失

内容的提问来源于stack exchange，提问作者Ryan