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-studio

服务起来了，浏览器打开localhost:8080却是一个光秃秃的骨架页——没有样式、没有按钮，控制台里前端资源 404 一路飘红。这是 Label Studio 源码开发新手最常撞上的第一堵墙：它的 Django 后端和 React 前端是两套独立进程，后端默认不会替你把前端构建出来，热重载（HMR）更得手动接线。搞清这一点，后面所有配置都不玄学。

一图看懂：为什么值得自己从源码搭

Label Studio 是一个支持文本、图像、音频、视频、时间序列等多类型数据标注与导出的开源平台，用 XML 配置即可拼装标注界面。生产环境可以直接装 pip 包或跑容器，但一旦你要改界面、加自定义标签、调 DataManager，就必须回到源码里开发。源码开发的核心链路是：label_studio/目录放 Django 后端（默认监听 8080），web/目录放前端工程（开发态监听 8010，通过 HMR 把热更新接到后端页面里）。

开工前 30 秒自检：红绿灯清单

按下面四条逐项过一遍，全绿再动手。每项都给了一条可直接敲的验证命令。

• 🟢Python 3.10 及以上：[pyproject.toml](https://link.gitcode.com/i/6d54d3b4517b43da5072886717b2071f)写死了>=3.10,<4，3.8/3.9 会在依赖解析阶段就卡住。验证：python3 --version
• 🟢bun 已安装：前端不再用 yarn/npm，锁文件是bun.lock，包管理器也声明为 bun 1.3.11。验证：bun --version
• 🟢uv 可用：Makefile 里所有后端命令都走uv run，没有 uv 就得先装。验证：uv --version
• 🟢内存 ≥ 4GB（建议 8GB）：前端 vite 构建加后端 Django 同时跑，2GB 机器会明显卡顿甚至 OOM。这一步没有命令可验证，凭经验判断。

任何一项变红就先补齐，别带病开工——后面每个关卡的失败率都会被环境问题放大。

关卡一：把代码拉起来

目标：拿到干净的源码树，装好前后端依赖，但先不追求跑通界面。

关键操作：

git clone https://gitcode.com/GitHub_Trending/la/label-studio cd label-studio

后端 Python 依赖由 uv 按pyproject.toml+uv.lock解析安装，首次执行任意make命令时会自动拉取，无需单独动作。前端依赖则必须显式装一次：

# 等价于 make frontend-install cd web && bun install --frozen-lockfile

验证成功：bun install无报错退出；仓库根目录出现.env的放置位置（下一步用到）。到此为止 8080 端口应该还是打不开的，属正常现象。

关卡二：让服务真正跑通，并接上热重载

目标：后端在 8080 正常出页面，前端在 8010 提供 HMR，改代码刷新都不用。

关键操作：分三步，顺序不能乱。

第一步，准备环境变量。在项目根目录创建.env，只有一项是必须的：

FRONTEND_HMR=true # 开启热模块替换，缺了它页面就是"骨架屏" FRONTEND_HOSTNAME=http://localhost:8010 # 可选，默认值即此 DJANGO_HOSTNAME=http://localhost:8080 # 可选，默认值即此

两个*_HOSTNAME只在改过默认端口或走远程开发时才需要动，本地开发保持默认即可——这也是跨域问题的第一排查点。

第二步，初始化数据库并启动后端。[Makefile](https://link.gitcode.com/i/eb66d24ff4ecf355b3efe8826fa12407)已经替你带好了DJANGO_DB=sqlite、DEBUG=true等开发环境变量：

make migrate-dev # 应用数据库迁移（SQLite，无需额外装库） make run-dev # 启动后端，监听 8080

第三步，开一个新终端启动前端 HMR：

make frontend-dev # 等价于 cd web && bun run dev，监听 8010

验证成功：两个终端都稳定输出、无报错；此时再访问http://localhost:8080，页面从骨架屏变成完整界面。判断热重载是否真的接通的办法很简单：随便改一处web/里的样式或文案，保存，浏览器在几秒内自动更新且不需要手动刷新。

关卡三：形成可复用的开发闭环

目标：把"改代码 → 验证 → 提交"固化成肌肉记忆，而不是每次现场想命令。

关键操作：日常只需记住这四个 Make 目标，覆盖绝大多数场景。

想要更强约束可以装 pre-push 钩子（make configure-hooks），推送前自动过 lint。想理解某个行为为什么这样，直接翻源码对应目录：后端入口在label_studio/manage.py，前端各组件职责在 web/README.md 里按apps/labelstudio、libs/editor、libs/datamanager三块讲得很清楚，官方部署向的说明可对照 docs/source/guide/install.md。

验证成功：你刚完成一次"改前端组件 → 浏览器自动更新 →make test通过 → 提交"的完整循环，且中途没有翻过任何文档。闭环成立，这套环境就归你了。

排错速查：症状 | 可能原因 | 解法

接下来去哪

三关通了之后，Label Studio 源码开发的地形其实不复杂：后端看label_studio/下各 app（tasks、projects、data_manager 是高频区），前端看web/libs/editor。建议按这个顺序往下走：

1. 读一遍 CONTRIBUTING.md，搞清代码组织与提交规范，改代码前先看一遍能省返工
2. 打开label_studio/annotation_templates/挑一个现有模板读懂标注配置与界面的对应关系，这是二次开发最常动的地方
3. 跑一次make test全流程，熟悉测试的粒度，给自己后续的改动补上回归保护

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio