FAQ

常见问题

本页面收集了 CCMage 使用过程中的常见问题和解决方案。

🚀 安装和配置

Q: 安装依赖时报错 "EACCES: permission denied"

A: 这是 npm 权限问题。解决方案：

# 方案 1: 使用 sudo（不推荐）
sudo npm run install:all

# 方案 2: 修复 npm 权限（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

# 重新安装
npm run install:all

Q: 端口 9999 被占用怎么办？

A: 查找并终止占用进程：

# macOS/Linux
lsof -i :9999
kill -9 <PID>

# Windows
netstat -ano | findstr :9999
taskkill /PID <PID> /F

# 或者修改端口
# 编辑 .env 文件
PORT=8888

Q: API Key 配置后仍然无法使用 AI 功能

A: 检查清单：

1. 确认 .env 文件在项目根目录
2. 确认环境变量格式正确（无引号）：

   ANTHROPIC_API_KEY=sk-ant-xxx

3. 重启后端服务
4. 查看后端日志确认 SDK 加载状态

📊 项目管理

Q: 添加项目后不显示

A: 可能的原因和解决方案：

1. 配置文件格式错误

   # 验证 JSON 格式
   cd .claude
   cat projects.json | jq .

2. 路径不存在

   • 检查项目路径是否正确
   • 相对路径是相对于 PROJECT_ROOT
   • 绝对路径要用完整路径

3. 需要刷新

   • 刷新浏览器页面
   • 重启后端服务

Q: Git 状态一直显示 "检测中"

A: 确认 Git 已安装：

git --version

# 如果未安装
# macOS
brew install git

# Ubuntu/Debian
sudo apt-get install git

# Windows
# 下载并安装 Git for Windows

Q: 项目状态不更新

A: 手动刷新项目状态：

1. 点击项目卡片上的刷新按钮
2. 或调用 API：

   curl http://localhost:9999/api/projects/:name/status

🚀 进程管理

Q: 启动项目失败 "未找到启动命令"

A: 手动配置启动命令：

编辑 .claude/projects.json：

{
  "projects": {
    "my-app": {
      "path": "my-app",
      "startCommand": "npm run dev"  // 添加这一行
    }
  }
}

Q: 服务启动后立即停止

A: 查看日志找出原因：

1. 打开日志查看器
2. 常见原因：
   • 端口已被占用
   • 依赖未安装
   • 配置文件错误

Q: 停止服务后进程仍在运行

A: 手动终止进程：

# 查找进程
ps aux | grep node

# 终止进程
kill -9 <PID>

# 或者查找端口占用
lsof -i :3000
kill -9 <PID>

Q: 日志显示乱码

A: 可能是字符编码问题：

1. 确认终端支持 UTF-8
2. 检查项目日志输出编码
3. 尝试重启服务

🤖 AI 功能

Q: AI 回复很慢或超时

A: 可能的原因：

1. 网络问题

   • 检查网络连接
   • 尝试使用代理：

     ANTHROPIC_BASE_URL=https://api.husanai.com

2. 请求过于复杂

   • 简化提示词
   • 分步骤提问

3. API 限流

   • 等待片刻后重试
   • 检查 API 配额

Q: AI 拆分的任务不合理

A: 优化提示词：

不好的描述：

做一个登录功能

好的描述：

实现用户登录功能，包括：
- 邮箱和密码登录
- JWT token 生成和验证
- 登录态保持（localStorage）
- 登录失败提示
技术栈：React + TypeScript + Express

Q: 如何切换 AI 引擎？

A: 两种方式：

1. 对话中切换：

   • 打开 AI 对话框
   • 点击引擎选择器
   • 选择不同引擎

2. 修改默认引擎：

   • 点击设置按钮
   • 选择默认引擎
   • 保存配置

Q: AI 历史记录丢失

A: 历史记录存储在：

backend/ai-history.json

如果文件丢失：

1. 检查是否被 .gitignore 忽略（正常）
2. 检查磁盘空间
3. 检查文件权限

💾 数据库

Q: Todo 数据丢失

A: 数据存储在 SQLite 数据库：

# 检查数据库文件
ls backend/project-manager.db

# 查询数据
cd backend
sqlite3 project-manager.db
SELECT * FROM todos;

Q: 数据库损坏

A: 重建数据库：

cd backend
# 备份（如果可能）
cp project-manager.db project-manager.db.backup

# 删除数据库
rm project-manager.db

# 重启服务器（会自动重新创建）
npm run dev

Q: 项目同步问题

A: 数据库和 projects.json 不同步：

# 删除数据库，重启服务会自动同步
cd backend
rm project-manager.db
npm run dev

🌐 浏览器和网络

Q: 前端无法连接到后端

A: 检查清单：

1. 后端是否启动：http://localhost:9999
2. 前端代理配置（vite.config.js）
3. CORS 设置
4. 防火墙规则

Q: SSE 连接断开

A: 可能原因：

1. 网络不稳定 - 刷新页面重连
2. 代理问题 - 某些代理不支持 SSE
3. 浏览器限制 - 更换浏览器尝试

Q: 页面加载慢

A: 优化方案：

1. 清除浏览器缓存
2. 检查是否有大量项目
3. 检查网络请求（开发者工具）

🔧 开发相关

Q: 修改代码后不生效

A: 检查热重载：

# 前端（Vite 自动热重载）
# 检查控制台是否有错误

# 后端（nodemon 自动重启）
# 检查 package.json 中的 nodemon 配置

Q: TypeScript 类型错误

A: 解决方案：

# 更新类型定义
npm install --save-dev @types/node @types/react

# 运行类型检查
npx tsc --noEmit

# 检查 tsconfig.json 配置

Q: ESLint 警告太多

A: 配置 ESLint：

# 创建 .eslintignore
echo "node_modules/" > .eslintignore
echo "dist/" >> .eslintignore

# 或关闭特定规则
# 编辑 .eslintrc.json

📱 系统兼容性

Q: macOS 下无法打开 VS Code

A: 配置 VS Code 命令行工具：

1. 打开 VS Code
2. 按 Cmd+Shift+P
3. 输入 "shell command"
4. 选择 "Install 'code' command in PATH"

Q: Windows 下路径问题

A: 使用正斜杠或转义反斜杠：

{
  "path": "C:/Users/username/project"
  // 或
  "path": "C:\\Users\\username\\project"
}

Q: Linux 下权限问题

A: 修复文件权限：

# 修复项目权限
chmod -R 755 /path/to/project

# 修复配置文件权限
chmod 644 .claude/projects.json

🆘 其他问题

Q: 如何备份数据？

A: 备份以下文件：

# 项目配置
.claude/projects.json

# 数据库
backend/project-manager.db

# AI 历史
backend/ai-history.json

# 环境变量（注意安全）
.env

Q: 如何完全重置？

A: 清除所有数据：

# 删除配置
rm .claude/projects.json

# 删除数据库
rm backend/project-manager.db

# 删除 AI 历史
rm backend/ai-history.json

# 保留 .env（包含 API Key）

# 重启服务
npm run dev

Q: 如何获取支持？

A: 寻求帮助的途径：

1. 查看文档：

   • 快速开始
   • 常见问题（本页面）

2. GitHub Issues：

   • 提交问题
   • 搜索已有问题

3. 查看日志：

   • 前端：浏览器 Console
   • 后端：终端输出

💡 最佳实践

避免常见错误

1. 不要提交敏感信息

   • .env 文件应该在 .gitignore 中
   • 不要上传 API Key

2. 定期备份

   • 定期备份数据库和配置
   • 使用版本控制

3. 保持更新

   • 定期检查更新
   • 查看 GitHub Releases

4. 测试环境

   • 重要操作前测试
   • 使用开发环境

📚 相关文档

• 常见问题（本页面）
• 开发指南
• 系统架构

---

找不到答案？ 在 GitHub Issues 提问