2、开发环境搭建：Node.js、Python环境、CVAT源码编译、Docker部署、调试工具配置
说实话，搭建开发环境这件事，往往是整个项目里最磨人的环节。我见过不少朋友，插件逻辑写得飞起，结果卡在环境配置上折腾了两天。嗯，这一章咱们就把这些坑提前填上。
2.1 Node.js 环境配置
CVAT 的前端插件开发，说白了离不开 Node.js。我个人习惯用 nvm 来管理 Node 版本，因为不同项目对版本要求不一样，你想想看，总不能每次升级都全局重装吧？
推荐版本：Node.js 16.x 或 18.x LTS 版本
安装步骤其实很简单：
- 先装 nvm（Windows 用户用 nvm-windows）
- 然后
nvm install 18.18.0 - 再
nvm use 18.18.0
我曾经遇到过一个问题：装完 Node 后，npm install 一直报权限错误。后来发现是 nvm 的安装路径里有中文空格。嗯，这里要注意——路径里千万别有中文和空格，血的教训。
小技巧：装完后跑一下 node -v 和 npm -v，确认版本号正常显示。如果报错，八成是环境变量没配好。
2.2 Python 环境配置
CVAT 的后端是 Python 写的，所以 Python 环境也得备好。我个人推荐用 conda 来管理，尤其是你要同时搞多个项目的时候。
| 组件 | 推荐版本 | 备注 |
|---|---|---|
| Python | 3.9 - 3.11 | 3.12 部分库还不兼容 |
| pip | 最新版 | 记得升级 pip install --upgrade pip |
| conda | 23.x | Miniconda 就够用 |
为什么推荐 conda？因为 CVAT 依赖的 OpenCV、NumPy 这些库，用 pip 装有时候会出二进制兼容问题。conda 在这方面省心很多。我在项目中遇到过好几次 pip 装 OpenCV 报错，换成 conda 一次过。
注意：不要用系统自带的 Python！尤其是 macOS 和 Linux 用户。系统 Python 是用来跑系统工具的，你乱装包可能会把系统搞崩。我见过有人把 macOS 的 Python 环境搞坏了，结果终端都打不开。
2.3 CVAT 源码编译
搞插件开发，你得先把 CVAT 源码跑起来。直接从 GitHub 拉代码：
git clone https://github.com/opencv/cvat.git
cd cvat
git checkout v2.8.2 # 选一个稳定版本
拉完代码后，前端编译需要跑：
cd cvat-ui
npm install
npm run build
这里有个坑——npm install 可能会卡在某个包上。我建议用淘宝镜像：
npm config set registry https://registry.npmmirror.com
后端的话，用 pip 装依赖：
cd cvat/apps
pip install -r requirements/development.txt
你想想看，前后端加起来几百个依赖，网络不好真的会崩溃。所以，我建议第一次编译时找个网络好的时间段，或者提前把依赖包下载好。
2.4 Docker 部署
说实话，Docker 是 CVAT 最推荐的部署方式。你不需要关心底层系统是什么，一个命令就能跑起来。
先装 Docker 和 Docker Compose：
- Windows/Mac：装 Docker Desktop
- Linux：装 docker-ce + docker-compose-plugin
然后直接跑：
docker compose up -d
等几分钟，浏览器打开 http://localhost:8080 就能看到 CVAT 界面了。
核心思路：Docker 部署适合快速验证，源码编译适合深度开发。我一般两个都配好——日常开发用源码，部署测试用 Docker。
我曾经踩过一个坑：Docker 跑起来后，发现插件加载不了。查了半天，原来是 Docker 的 volume 挂载路径不对。嗯，这里要注意——如果你要开发插件，记得把插件目录挂载到容器里：
volumes:
- ./my-plugin:/opt/cvat/plugins
2.5 调试工具配置
调试工具这块，我分成前端和后端来说。
前端调试
前端插件本质上是 React 组件，所以 Chrome DevTools 就够了。但有几个要点：
- 装 React Developer Tools 扩展
- 用
console.log调试时，记得在插件代码里加// @ts-ignore避免类型报错 - CVAT 的 Redux 状态可以用 Redux DevTools 查看
我个人习惯在插件里加一个调试模式开关：
const DEBUG = true;
if (DEBUG) {
console.log('[MyPlugin] 当前状态:', state);
}
后端调试
后端是 Django 写的，调试方式很成熟：
- 用
pdb设置断点：import pdb; pdb.set_trace() - 或者用 VSCode 的 Python 调试器，配置 launch.json
- 查看 Django 日志：
docker logs cvat_backend -f
我的经验：后端调试最烦的是数据库问题。我建议装一个 DBeaver 或者 TablePlus，直接连 CVAT 的 PostgreSQL 数据库，查看数据状态比看日志快多了。
2.6 整体架构一览
说了这么多，咱们用一张图来总结整个开发环境的结构：
这张图展示的是我常用的开发模式：左边是开发机，右边是 Docker 容器。源码在开发机上编辑，通过 volume 映射到容器里，实现热更新。调试工具两边都能用，前端用 Chrome DevTools，后端用 pdb 或者 IDE 调试器。
总结一下：环境搭建的核心就三件事——Node.js 搞定前端、Python 搞定后端、Docker 搞定部署。调试工具是辅助，但能帮你省下大量排查问题的时间。
嗯，这一章的内容就到这儿。环境搭好了，下一章咱们就可以真正动手写插件了。