如何搭建 Label Studio 开发环境：4步从源码到本地热重载
【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio
你克隆完 Label Studio 仓库，后端起来了，页面却是白屏；前端 8010 也跑着，刷新后还是连不上——这是搭这套环境时最典型的现场。Label Studio 是一个多类型数据标注工具，支持图片、文本、音频、视频和时间序列，前后端分离：React 前端用 Vite 跑在 8010 端口，Django 后端跑在 8080 端口，两边各自装依赖、各自起服务。走完下面四步，你就能独立完成 Label Studio 开发环境搭建，并且改一行代码立刻在浏览器里看到结果。
启动前的准备
先确认机器满足最低要求：
- Python 3.10+（pyproject.toml 要求
>=3.10） - Bun 运行时（前端用它装依赖和起服务）
- Poetry（官方 README 推荐的依赖管理方式）
- 内存 4GB 以上，磁盘 2GB 空闲；Linux/macOS 直接跑，Windows 建议用 WSL2
整体架构一句话：web/是 React 前端，label_studio/是 Django 后端，两者通过本地端口通信，开发时各自开一个终端。
第一次把项目跑起来 🚀
拿代码
克隆仓库并进入目录，这是后续所有命令的工作根目录：
git clone https://gitcode.com/GitHub_Trending/la/label-studio cd label-studio成功标志：ls能看到label_studio/、web/、Makefile三样东西。
装依赖
后端依赖用 Poetry 装，前端依赖进web/用 Bun 装：
pip install poetry poetry install # 后端 Python 依赖 make frontend-install # 前端依赖，等价于 cd web && bun install成功标志：两条命令都正常结束、无依赖冲突报错。
起服务
先做数据库迁移，再分别起后端和前端（两个终端）：
make migrate-dev # 终端1：初始化 SQLite 数据库 make run-dev # 终端1：起 Django 后端，监听 8080 make frontend-dev # 终端2：起 Vite 前端，监听 8010成功标志：打开 http://localhost:8080 能看到 Label Studio 的登录页面。
改一行代码验证热重载 🔥
先让 Django 知道要启用热模块替换，在项目根目录建一个.env文件：
cat > .env <<EOF FRONTEND_HMR=true EOF保存后端服务，让配置生效。然后随便找一个渲染文本的前端组件，改一行展示文案：
- <div className="ls-title">Projects</div> + <div className="ls-title">我的项目</div>保存文件，浏览器里的页面会自动更新，不用重启任何服务。这就是 HMR 在工作的证据。
看懂项目目录结构 🗂
label-studio/ ├── label_studio/ # Django 后端 │ ├── manage.py # 后端入口 │ ├── core/ # 核心配置与路由 │ └── tasks/ # 任务与标注相关模型 ├── web/ # 前端 monorepo │ ├── apps/labelstudio/ # 主应用 │ └── libs/editor/ # 标注编辑器核心库 ├── docs/ # 官方文档源码 ├── Makefile # 开发命令集合 └── pyproject.toml # Python 依赖声明几个日常会碰到的文件：
- Makefile：
run-dev、frontend-dev等命令都在这，日常只跟它打交道 - label_studio/manage.py：Django 入口，手动跑
migrate、runserver都用它 - web/package.json：前端脚本定义，
dev、build、test:unit都在这 - web/README.md：前端环境与 HMR 配置的权威说明
常用命令速查 ⚡
| 命令 | 作用 |
|---|---|
make run-dev | 启动后端开发服务器（SQLite + 8080 端口） |
make frontend-dev | 启动前端热重载服务（8010 端口） |
make frontend-install | 安装前端 Bun 依赖 |
make migrate-dev | 应用数据库迁移 |
make makemigrations-dev | 改了模型后生成迁移文件 |
make shell-dev | 进 Django shell，调试数据模型 |
make test | 跑后端单元测试 |
make fmt | 按分支 diff 格式化代码 |
出了问题对照排查 🛠
| 现象 | 原因 | 解决 |
|---|---|---|
| 页面白屏、样式全丢 | 前端没起或.env缺FRONTEND_HMR=true | 跑make frontend-dev，补上.env再重启后端 |
| 8080 拒绝连接 | 后端没跑或没做迁移 | 先make migrate-dev，再make run-dev |
bun: command not found | 没装 Bun 运行时 | 先安装 Bun，再跑make frontend-install |
更多报错细节可以翻 官方安装文档 和 故障排除指南。
环境跑通后，建议接着做三件事：
- 打开
label_studio/annotation_templates/里的现成模板，照着写一份自己的标注配置； - 按 ML 后端文档 接一个模型，体验预标注；
- 跑一遍
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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
