ColaFlow/DEBUGGING_GUIDE.md

ColaFlow API 连接问题诊断指南

修复完成时间

2025-11-03

问题描述

项目列表页面无法显示项目数据，前端可以访问但无法连接到后端 API。

已实施的修复

1. 增强 API 客户端调试（lib/api/client.ts）

• 添加了 API URL 的控制台日志输出
• 为每个请求添加详细的日志记录
• 增强错误处理和错误信息输出
• 捕获网络错误并输出详细信息

2. 改进项目页面错误显示（app/(dashboard)/projects/page.tsx）

• 显示详细的错误信息（而不是通用消息）
• 显示当前使用的 API URL
• 添加故障排查步骤
• 添加重试按钮
• 添加控制台调试日志

3. 增强 useProjects Hook（lib/hooks/use-projects.ts）

• 添加详细的日志记录
• 减少重试次数以更快失败（从 3次 降至 1次）
• 捕获并记录所有错误

如何使用调试功能

步骤 1: 重启前端开发服务器

cd colaflow-web
npm run dev

重启是必要的，因为 Next.js 需要重新加载以应用环境变量更改。

步骤 2: 打开浏览器开发工具

1. 访问 http://localhost:3000/projects
2. 按 F12 打开开发者工具
3. 切换到 Console 标签页

步骤 3: 查看控制台输出

你应该看到以下日志：

[API Client] API_URL: http://localhost:5167/api/v1
[API Client] NEXT_PUBLIC_API_URL: http://localhost:5167/api/v1
[useProjects] Fetching projects... {page: 1, pageSize: 20}
[API Client] Request: {method: 'GET', url: 'http://localhost:5167/api/v1/projects?page=1&pageSize=20', endpoint: '/projects?page=1&pageSize=20'}

如果出现错误，你会看到：

[API Client] Network error: {url: '...', error: 'Failed to fetch', errorObject: ...}
[useProjects] Fetch failed: TypeError: Failed to fetch
[ProjectsPage] Error loading projects: TypeError: Failed to fetch

步骤 4: 检查网络请求

1. 在开发者工具中切换到 Network 标签页
2. 刷新页面
3. 查找对 http://localhost:5167/api/v1/projects 的请求
4. 检查请求状态：
   • 失败/红色: 服务器未响应
   • 404: 路由不存在
   • 500: 服务器错误
   • CORS错误: 跨域配置问题

步骤 5: 查看错误屏幕

如果 API 无法连接，页面会显示详细的错误卡片：

• Error Details: 具体的错误消息
• API URL: 当前配置的 API 地址
• Troubleshooting Steps: 故障排查步骤
• Retry按钮: 点击重试

常见问题诊断

问题 1: "Failed to fetch" 错误

原因: 后端服务器未运行或无法访问

解决方案:

# 检查后端是否在运行
curl http://localhost:5167/api/v1/health

# 如果失败，启动后端服务器
cd ColaFlow.Api
dotnet run

问题 2: API URL 使用默认端口 5000

原因: 环境变量未正确加载

解决方案:

1. 检查 .env.local 文件是否存在且包含：

   NEXT_PUBLIC_API_URL=http://localhost:5167/api/v1
   

2. 重启 Next.js 开发服务器
3. 确保没有 .env 文件覆盖设置

问题 3: CORS 错误

原因: 后端未配置允许前端域名

解决方案: 检查后端 CORS 配置（ColaFlow.Api/Program.cs）:

builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowFrontend", policy =>
    {
        policy.WithOrigins("http://localhost:3000")
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});

问题 4: 404 错误

原因: API 路由不存在或路径不正确

解决方案:

1. 检查后端路由配置
2. 确认 API 前缀是 /api/v1
3. 检查控制器路由是否正确

验证修复

成功的日志输出示例

[API Client] API_URL: http://localhost:5167/api/v1
[useProjects] Fetching projects...
[API Client] Request: GET http://localhost:5167/api/v1/projects?page=1&pageSize=20
[API Client] Response: {url: '...', status: 200, data: [...]}
[useProjects] Fetch successful: [...]
[ProjectsPage] State: {isLoading: false, error: null, projects: [...]}

检查清单

• 控制台显示正确的 API URL (5167端口)
• 网络请求显示 200 状态码
• 控制台显示成功的响应数据
• 页面显示项目列表或"No projects yet"消息
• 没有错误消息或红色日志

下一步行动

如果问题仍然存在：

1. 检查后端日志: 查看后端控制台输出
2. 测试 API 直接访问: 使用 curl 或 Postman 测试 API
3. 检查防火墙: 确保端口 5167 未被阻止
4. 检查端口冲突: 确认没有其他程序使用 5167 端口

如果问题已解决：

1. 移除调试日志（生产环境）
2. 添加更好的错误处理
3. 考虑添加 API 健康检查端点
4. 实施重试逻辑和超时处理

相关文件

• colaflow-web/lib/api/client.ts - API 客户端配置
• colaflow-web/lib/hooks/use-projects.ts - Projects 数据 hook
• colaflow-web/app/(dashboard)/projects/page.tsx - 项目列表页面
• colaflow-web/.env.local - 环境变量配置

Git 提交

• Commit: fix(frontend): Add comprehensive debugging for API connection issues
• Branch: main
• Files changed: 3 (client.ts, use-projects.ts, page.tsx)

---

注意: 这些调试日志在开发环境很有用，但在生产环境应该移除或使用日志级别控制。