qinglong开发环境搭建：从源码编译到本地调试完整流程
项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong 还在为定时任务管理平台的开发环境配置而烦恼？本文将从零开始，手把手教你搭建qinglong的完整开发环境，涵盖前端、后端、数据库配置到本地调试的全流程。
环境准备与前置依赖
在开始之前，确保你的系统满足以下基本要求：
| 组件 | 最低版本 | 推荐版本 | 用途说明 |
|---|---|---|---|
| Node.js | 16.x | 18.x+ | JavaScript运行时环境 |
| npm | 8.x | 9.x+ | 包管理工具 |
| pnpm | 7.x | 8.3.1+ | 高性能包管理器 |
| Python | 3.8 | 3.9+ | 脚本执行环境 |
| Git | 2.x | 2.30+ | 版本控制系统 |
系统环境检查
首先验证你的开发环境是否满足基本要求：
# 检查Node.js版本
node --version
# 检查npm版本
npm --version
# 检查Python版本
python3 --version
# 检查Git版本
git --version
如果缺少任何组件，请先安装相应的软件包。
源码获取与项目初始化
克隆项目仓库
# 克隆项目到本地
git clone https://gitcode.com/GitHub_Trending/qi/qinglong.git
cd qinglong
# 查看项目结构
ls -la
项目采用典型的Monorepo结构，包含前端（src目录）和后端（back目录）代码。
环境配置文件设置
# 复制环境配置文件模板
cp .env.example .env
编辑.env文件，配置必要的环境变量：
# gRPC服务端口
GRPC_PORT=5500
# 后端API服务端口
BACK_PORT=5600
# 前端服务端口
PORT=5700
# 日志级别
LOG_LEVEL='info'
# JWT密钥（用于身份验证）
JWT_SECRET=your-secret-key-here
# JWT过期时间
JWT_EXPIRES_IN=7d
依赖安装与构建配置
安装pnpm包管理器
# 全局安装推荐版本的pnpm
npm install -g pnpm@8.3.1
安装项目依赖
# 安装所有依赖包
pnpm install
这个过程会安装前后端的所有依赖，包括：
- 后端依赖: Express.js、gRPC、数据库驱动等
- 前端依赖: React、Ant Design、Umi.js等
- 开发工具: TypeScript、Prettier、Nodemon等
项目构建配置解析
qinglong项目采用TypeScript开发，配置了多个构建目标：
开发环境启动与调试
同时启动前后端服务
# 使用concurrently同时启动前后端
pnpm start
这个命令会启动两个服务：
- 前端开发服务器：运行在5700端口
- 后端API服务器：运行在5600端口
分别启动服务（推荐用于调试）
# 终端1：启动后端服务
pnpm run start:back
# 终端2：启动前端服务
pnpm run start:front
服务健康检查
启动成功后，可以通过以下方式验证服务状态：
# 检查后端API服务
curl http://localhost:5600/api/health
# 检查前端服务
curl http://localhost:5700
数据库配置与初始化
qinglong使用SQLite作为默认数据库，数据文件位于data/目录。首次启动时会自动创建必要的数据库表结构。
数据库连接配置
查看数据库相关配置：
// back/config/const.ts 中的数据库配置
export const DATA_DIR = process.env.QL_DIR || path.join(__dirname, '../../data');
export const DB_PATH = path.join(DATA_DIR, 'data.db');
数据库初始化流程
开发调试技巧
热重载配置
项目配置了Nodemon用于后端代码的热重载：
// nodemon.json 配置
{
"watch": ["back/"],
"ext": "ts,json",
"ignore": ["back/**/*.spec.ts"],
"exec": "ts-node -r tsconfig-paths/register back/app.ts"
}
TypeScript调试配置
创建.vscode/launch.json文件进行调试配置：
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Backend",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/back/app.ts",
"outFiles": ["${workspaceFolder}/static/build/**/*.js"],
"envFile": "${workspaceFolder}/.env",
"runtimeArgs": ["-r", "ts-node/register"]
}
]
}
常用开发命令
# 构建前端生产版本
pnpm run build:front
# 构建后端生产版本
pnpm run build:back
# 生成gRPC协议文件
pnpm run gen:proto
# 代码格式化
pnpm run prettier
常见问题排查
依赖安装失败
如果遇到依赖安装问题，尝试清理缓存：
# 清理pnpm缓存
pnpm store prune
# 删除node_modules重新安装
rm -rf node_modules
pnpm install
端口冲突处理
如果默认端口被占用，修改.env文件中的端口配置：
# 修改为其他可用端口
BACK_PORT=5601
PORT=5701
GRPC_PORT=5501
数据库权限问题
确保项目目录有写入权限：
# 给数据目录赋予写入权限
chmod -R 755 data/
开发最佳实践
代码结构规范
遵循项目的代码组织结构：
src/ # 前端源码
├── components/ # 公共组件
├── pages/ # 页面组件
├── utils/ # 工具函数
└── styles/ # 样式文件
back/ # 后端源码
├── api/ # API路由
├── config/ # 配置文件
├── services/ # 业务服务
└── shared/ # 共享工具
提交规范
项目配置了Git Hooks，提交前会自动进行代码格式化：
# 提交前会自动运行prettier格式化代码
git add .
git commit -m "feat: 添加新功能"
总结
通过本文的详细指导，你应该已经成功搭建了qinglong的完整开发环境。这个环境支持：
- ✅ 前后端代码的热重载开发
- ✅ TypeScript类型检查和编译
- ✅ 数据库自动初始化和管理
- ✅ 完整的调试工具链配置
- ✅ 代码质量检查和格式化
现在你可以开始进行功能开发、bug修复或者自定义扩展了。开发过程中如果遇到问题，可以查阅项目的README文档或者检查相关的配置文件。
Happy coding！ 🚀
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
