Label Studio 源码开发环境避坑指南：热重载配置一次讲清

Label Studio 源码开发环境避坑指南热重载配置一次讲清【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio 开发环境搭建这件事我按仓库里 Makefile 和文档的说法完整走了一遍Python 侧、数据库、前端热重载真正卡人的地方其实就四个。这篇是踩坑记录目标是你照着做一遍就能把「改代码→浏览器自动刷新」的闭环跑起来不用再去翻一堆零散资料。先把「跑起来」的标准定清楚我习惯先问一句到底什么状态才算开发环境就绪对 Label Studio 来说就是三件事浏览器打开 http://localhost:8080 能登录、能建项目、能导入数据改动前端源码后8080 页面上立刻能看到变化不用手动刷新数据库是本地 SQLite关掉终端数据还在下次继续不用重新初始化。注意第 2 条热重载不是前端自己刷新那么简单它要求 Django 端知道前端开发服务器的地址。很多教程漏掉这半句你就得到了一个「刷新才生效」的假热重载。后面会专门说。先把代码拉下来git clone https://gitcode.com/GitHub_Trending/la/label-studio cd label-studio仓库结构很直白label_studio/ 是 Django 后端manage.py 是入口web/ 是前端里面分三块——apps/labelstudio 主应用、libs/editor 标注编辑器核心库、libs/datamanager 数据管理器。所有开发命令都收敛在根目录的 Makefile 里这一点很重要后面所有命令我都只讲 make 目标不手敲长命令。Python 依赖别自己装这个仓库已经替你把工具选好了⚠️ 这是第一个坑。网上不少老教程让你用 Poetry 装 Python 依赖但现在的仓库里压根没有 poetry 配置取而代之的是 uv根目录有 pyproject.toml 和 uv.lockMakefile 里所有后端命令都是uv run ...的形式。也就是说 Python 环境由 uv 按锁文件自动管理你唯一要做的是装好 uv 本身然后一切交给 make。前端同理web/ 下用的是 bun 而不是 yarnweb/package.json 配合 bun.lock 工作。你不用纠结版本bun install就行后面会用现成的 make 目标封装这一步。 一句话原则这个仓库里凡是 Makefile 覆盖了的操作都不要手动敲。Makefile 里写死了 DEBUG、日志目录、settings 模块这些环境变量手敲很容易漏。数据库初始化让 SQLite 在幕后干好活Label Studio 后端默认就能用 SQLite 跑开发不用先起 MySQL 或 Postgres。看 Makefile 里run-dev目标的完整写法就明白了# make run-dev 实际执行的内容节选 DJANGO_DBsqlite LOG_DIRtmp DEBUGtrue \ LOG_LEVELDEBUG DJANGO_SETTINGS_MODULEcore.settings.label_studio \ uv run python label_studio/manage.py runserver四个变量各司其职DJANGO_DBsqlite指定数据库对应 core/settings/label_studio.py 里读环境变量的那段LOG_DIRtmp把日志丢到临时目录DEBUGtrue打开调试模式DJANGO_SETTINGS_MODULE指定用哪套配置。所以后端启动流程就是两条命令make migrate-dev # 首次必做应用数据库迁移 make run-dev # 启动 Django 开发服务器看到 8080 端口的服务起来后先别急着访问。此刻页面上不会有前端资源——因为前端还没构建或启动这是正常现象别怀疑自己装坏了。前端热重载.env 文件其实要你自己写 到这一步是本文的核心web/README.md 写得明明白白要让 Django 开启热模块替换HMR需要在项目根目录注意不是 web/ 目录下放一个.env文件。它不在仓库里得手动创建# 项目根目录的 .env FRONTEND_HMRtrue FRONTEND_HOSTNAMEhttp://localhost:8010 DJANGO_HOSTNAMEhttp://localhost:8080三个变量FRONTEND_HMRtrue是总开关后两个告诉 Django 前端开发服务器和 Django 各自在哪默认值就是上面这两行大多数机器不用改。然后启动前端make frontend-dev # 等价于 cd web bun run dev它内部会先装依赖再拉起开发服务器服务跑在 8010 端口。此时回到 8080 的页面改一行 libs/editor 里的源码保存浏览器自动更新——热重载才算真正闭环。热重载不生效时先查这两项实际排错时我九成情况查的就是这两个位置.env 放错目录或变量名拼错。它必须在仓库根目录且是FRONTEND_HMR全大写。放进了 web/ 里Django 根本读不到现象就是页面不自动刷新。端口地址不匹配。如果你改过 8080 或 8010DJANGO_HOSTNAME/FRONTEND_HOSTNAME要同步改改完前端要重启才生效改 .env 后 Django 那边也要重启。另外两个小现象提前打预防针只看到 Django 启动日志、前端终端报依赖错误一般是 bun 依赖没装全重跑一次make frontend-dev让它自己补装即可嫌每次启动慢可以直接用仓库提供的 Docker 路线Makefile 里的docker-dev-setupdocker-run-dev目标配合 docker-compose.yml但本地调试体验上上面那套裸跑更快。跑起来之后常用开发命令速查环境建好后的日常基本就住在这些 make 目标里全部定义在 Makefilemake run-dev/make migrate-dev/make makemigrations-dev跑服务、迁移、生成迁移make frontend-dev/make frontend-watch热重载开发 / 文件变更持续构建make test跑后端单测pytest自动排除集成测试make fmt/make fmt-checkpre-commit 格式化和检查想让它挂在 git push 上执行一次make configure-hooksmake update-urls重新生成 core/all_urls.json改后端路由后有用日常调试建议两个终端一个挂后端一个挂前端都开着热重载。后端 Python 代码改动 Django 会自动重载前端改动浏览器自动刷新中间只剩你自己的键盘在动。参考资料都在这几个地方docs/source/guide/install.md 讲各种安装方式web/README.md 是前端命令和 .env 的权威说明CONTRIBUTING.md 则讲了贡献流程和开发规范动手改源码前值得扫一眼。【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考