New-API 开发调试手册

1. 环境准备

• Node.js 环境
• Go 开发环境
• Git
• 编辑器（推荐 VSCode 或 GoLand）

2. 项目初始化

# 克隆项目
git clone https://github.com/Calcium-Ion/new-api.git
cd /Users/liangfeng/evn/projects/new-api

# 创建环境配置文件
cp .env.example .env

3. 开发模式一：前端开发模式

适用于主要进行前端代码修改的场景。

3.1 启动后端服务

cd /Users/liangfeng/evn/projects/new-api
FRONTEND_BASE_URL=http://localhost:5173 go run main.go

3.2 启动前端开发服务器

cd /Users/liangfeng/evn/projects/new-api/web
npm install
npm run dev

特点：

• 前端代码修改后自动热重载
• 后端提供 API 服务
• 前端通过 FRONTEND_BASE_URL 连接后端 API

4. 开发模式二：后端开发模式

适用于主要进行后端代码修改的场景。

4.1 构建前端代码

cd /Users/liangfeng/evn/projects/new-api/web
npm install
npm run build

4.2 启动后端服务

cd /Users/liangfeng/evn/projects/new-api
go run main.go

特点：

• 前端代码已编译为静态文件
• 后端代码修改后需要重启服务
• 适合调试后端 API 和业务逻辑

5. 数据库配置

默认使用 SQLite 数据库，如需使用 MySQL，在 .env 文件中配置：

SQL_DSN=user:password@tcp(127.0.0.1:3306)/dbname?parseTime=true

6. 调试技巧

6.1 后端调试

• 使用 go run 启动时可以设置环境变量：

ENABLE_PPROF=true go run main.go

• 查看日志：所有系统日志会输出到控制台

6.2 前端调试

• 使用浏览器开发者工具
• 前端开发服务器默认端口：5173
• API 请求监控：Network 面板

7. 常见问题

7.1 web/dist: no matching files found

解决方案：需要先构建前端代码

cd /Users/liangfeng/evn/projects/new-api/web
npm run build

7.2 前后端连接问题

检查：

• 后端 API 地址配置
• CORS 设置
• 环境变量 FRONTEND_BASE_URL 配置

8. 生产环境构建

8.1 前端构建

cd /Users/liangfeng/evn/projects/new-api/web
npm run build

8.2 后端构建

cd /Users/liangfeng/evn/projects/new-api
go build

9. 注意事项

1. 首次启动会自动创建 root 用户（密码：123456）
2. 开发时建议启用内存缓存：MEMORY_CACHE_ENABLED=true
3. 代码提交前请运行 npm run lint:fix 格式化前端代码

10. 待完善内容

• Docker 开发环境配置
• 单元测试流程
• CI/CD 流程
• 性能调优指南
• 多节点部署调试