故障排查指南
本文档帮助您解决测试运行过程中遇到的常见问题。
目录
连接问题
问题: cURL error 7 - Failed to connect
错误信息:
cURL error 7: Failed to connect to localhost port 8000: Connection refused可能原因:
- API 服务器未启动
- 端口配置错误
- 防火墙阻止连接
解决方案:
- 检查 API 服务器状态
bash
# 检查端口是否监听
lsof -i :8000
# 或
netstat -tlnp | grep 8000- 确认服务器正在运行
bash
# 查看进程
ps aux | grep php- 验证 API_BASE_URL 配置
bash
# 测试连接
curl http://localhost:8000/- 检查防火墙
bash
# macOS
sudo pfctl -sr | grep 8000
# Linux
sudo iptables -L -n | grep 8000问题: cURL error 6 - Could not resolve host
错误信息:
cURL error 6: Could not resolve host: your-api-server解决方案:
- 检查 hosts 文件
bash
cat /etc/hosts- 使用 IP 地址测试
bash
curl http://127.0.0.1:8000/- 检查 DNS 配置
bash
nslookup your-api-server超时问题
问题: cURL error 28 - Operation timed out
错误信息:
cURL error 28: Operation timed out after 60000 milliseconds可能原因:
- API 处理时间过长
- 网络延迟高
- 超时设置过短
解决方案:
- 增加超时时间
php
// 在测试中修改
$this->httpClient = new Client([
'base_uri' => $this->baseUrl,
'timeout' => 300, // 增加到 300 秒
'verify' => false,
]);- 手动测试 API 响应时间
bash
time curl http://localhost:8000/api/app/copy/marketing- 检查后端日志
bash
# 查看应用日志
tail -f api/runtime/log/$(date +%Y%m%d).log- 检查 AIGC 服务状态
问题: PHPUnit 整体超时
错误信息:
PHP Fatal error: Maximum execution time of 30 seconds exceeded解决方案:
- 修改 php.ini
ini
max_execution_time = 300- 在测试中临时设置
php
public function testLongRunning(): void
{
set_time_limit(300);
// 测试代码
}- 使用 phpunit.xml 配置
xml
<php>
<ini name="max_execution_time" value="300"/>
</php>认证问题
问题: 401 Unauthorized
错误信息:
HTTP 401 Unauthorized可能原因:
- 缺少认证令牌
- 令牌过期
- 签名错误
解决方案:
检查认证中间件 查看
app/base/middleware/RouteAuth.php和SignAuth.php确认测试绕过认证 检查路由是否在公开路由列表中
查看后端日志中的认证失败原因
bash
tail -f api/runtime/log/$(date +%Y%m%d).log | grep -i auth问题: API 密钥无效
错误信息:
API key is invalid or expired解决方案:
- 检查环境变量配置
bash
# 查看当前环境变量
env | grep VOLCENGINE
env | grep ALIYUN- 检查 .env 文件
bash
cat api/.env | grep -E "(VOLC|ALI)"- 验证密钥在控制台中是否有效
API 响应问题
问题: JSON 解析失败
错误信息:
json_decode() expects parameter 1 to be string, array given解决方案:
- 查看原始响应
php
$responseBody = (string)$response->getBody();
echo "Raw response: " . $responseBody . "\n";- 检查响应 Content-Type
php
$contentType = $response->getHeader('Content-Type')[0] ?? '';
echo "Content-Type: " . $contentType . "\n";- 验证 API 返回的是 JSON 而非 HTML 错误页
问题: 业务错误码非 0
错误信息:
Failed asserting that 1 matches expected 0.解决方案:
- 查看完整的错误响应
php
echo "Error message: " . ($body['message'] ?? 'No message') . "\n";- 检查后端日志
bash
tail -f api/runtime/log/$(date +%Y%m%d).log- 验证请求参数 确认所有必填参数都已提供且格式正确
测试框架问题
问题: Class not found
错误信息:
Fatal error: Uncaught Error: Class 'PHPUnit\Framework\TestCase' not found解决方案:
- 确认 Composer 依赖已安装
bash
cd api
composer install确认 autoload 已加载 检查测试文件顶部的 autoload 加载代码
运行
composer dump-autoload
bash
composer dump-autoload问题: Test method not found
错误信息:
No tests found in class "AigcCopyPipelineTest"解决方案:
- 确认测试方法以
test开头
php
// ✅ 好
public function testMarketingCopyGeneration(): void {}
// ❌ 不好
public function marketingCopyGeneration(): void {}- 确认方法是 public
php
// ✅ 好
public function testSomething(): void {}
// ❌ 不好
protected function testSomething(): void {}- 使用
--list-tests查看可用测试
bash
vendor/bin/phpunit tests/api/AigcCopyPipelineTest.php --list-tests性能问题
问题: 测试运行太慢
解决方案:
- 只运行必要的测试
bash
# 只运行特定测试
vendor/bin/phpunit --filter testMarketingCopyGeneration
# 排除慢速测试
vendor/bin/phpunit --exclude-group slow- 使用测试缓存
bash
vendor/bin/phpunit --cache-result- 并行运行
bash
composer require --dev brianium/paratest
vendor/bin/paratest -p4问题: 内存耗尽
错误信息:
Fatal error: Allowed memory size of 134217728 bytes exhausted解决方案:
- 增加 PHP 内存限制
php
// 在测试文件开头
ini_set('memory_limit', '512M');- 在 phpunit.xml 中配置
xml
<php>
<ini name="memory_limit" value="512M"/>
</php>- 优化测试，避免加载过多数据
获取帮助
如果以上方案都无法解决问题：
- 收集诊断信息
bash
# PHP 版本
php -v
# PHPUnit 版本
vendor/bin/phpunit --version
# Composer 依赖
composer show
# 环境变量
env | grep -E "(API|VOLC|ALI|APP)"- 查看完整的错误堆栈
bash
vendor/bin/phpunit --debug- 检查后端日志
bash
# 应用日志
ls -la api/runtime/log/
# Web 服务器日志
# Nginx: /var/log/nginx/
# Apache: /var/log/apache2/