Backstage 开发环境容器化:基于 Dev Containers 的完整实战指南
Backstage 开发环境容器化:基于 Dev Containers 的完整实战指南
本指南以 Backstage 仓库内置的 .devcontainer 配置为核心,系统讲解如何在 Docker 容器中搭建完整、一致的 Backstage 开发环境,覆盖从环境准备、镜像构建、依赖安装到端口转发与问题排查的全流程。读完本文,你将掌握通过 VS Code 或 IntelliJ IDEA 一键进入容器化开发环境、启动前端与后端服务(端口 3000 / 7007)、运行 TechDocs 与端到端测试的具体方法,并理解仓库中每个 Dev Container 配置文件的底层作用。
什么是 Dev Containers?
Dev Containers(Development Containers)允许你将一个 Docker 容器当作完整功能的开发环境来使用。所有依赖、工具和配置都定义在容器中,本地机器无需安装 Node.js、Python 等任何工具链,即可获得开箱即用且跨机器、跨操作系统完全一致的开发体验。
Backstage 仓库在根目录的 .devcontainer 文件夹中提供了完整配置,包含四个文件:
| 文件 | 作用 |
|---|---|
| .devcontainer/devcontainer.json | Dev Container 的入口描述文件,定义镜像构建方式、端口转发、扩展与设置 |
| .devcontainer/Dockerfile | 基础镜像定义,负责安装 Chromium 与系统编译依赖 |
| .devcontainer/setup.sh | 容器创建后自动执行的初始化脚本,安装 Yarn 依赖与 TechDocs Python 环境 |
| .devcontainer/devcontainer.env | 注入容器的环境变量文件 |
前置条件
开始之前,请确保本地已安装以下软件:
- Docker Desktop(Linux 上为 Docker Engine):Mac 用户安装 Docker Desktop for Mac,Windows 用户安装 Docker Desktop for Windows,Linux 用户安装 Docker Engine。
- Visual Studio Code 或 IntelliJ IDEA Ultimate:两种编辑器均可使用 Dev Containers。
注意:IntelliJ IDEA Community Edition 不支持 Dev Containers,必须使用 Ultimate(付费)版本。
- Dev Containers 扩展:
- VS Code:在 Extensions 视图(
Ctrl/Cmd + Shift + X)中搜索 "Dev Containers" 并安装(扩展 ID 为ms-vscode-remote.remote-containers)。 - IntelliJ IDEA:Ultimate 版本自带 Dev Containers 支持,无需额外插件。
- VS Code:在 Extensions 视图(
系统资源要求
仓库在 devcontainer.json 中通过 hostRequirements 显式声明了最低资源需求:
- CPU:至少 2 核
- 内存:至少 4GB
- 存储:至少 32GB 可用磁盘空间
这些限制同时会在支持该规范的编辑器中作为环境检查提示展示。
快速开始
方式一:克隆仓库后直接在容器中打开
-
Fork 并克隆 Backstage 仓库(若尚未完成):
git clone https://github.com/<your-username>/backstage.git cd backstage如果你使用本仓库的镜像副本,直接克隆当前仓库地址即可:
git clone https://gitcode.com/GitHub_Trending/ba/backstage.git。 -
在 VS Code 中打开:
code . -
在容器中重新打开:
- VS Code 检测到
.devcontainer文件夹后,会弹出通知询问是否在容器中重新打开文件夹,点击 "Reopen in Container"。 - 或者打开命令面板(
Ctrl/Cmd + Shift + P),执行 "Dev Containers: Reopen in Container"。
- VS Code 检测到
-
等待容器构建完成:
- 首次打开容器时,需要几分钟时间构建 Docker 镜像并安装全部依赖,VS Code 会在右下角显示进度。
- 构建完成后,setup.sh 会自动执行
yarn install,并为 TechDocs 创建 Python 虚拟环境、安装mkdocs-techdocs-core。
-
开始开发:
- 设置完成后,终端中会显示一条欢迎横幅,提示环境已就绪。
- 在 VS Code 中打开新终端(
Ctrl/Cmd + ~),运行yarn start启动 Backstage。
方式二:从命令面板重建并打开
如果之前已经构建过容器,或需要强制重建:
- 在 VS Code 中打开 Backstage 仓库
- 打开命令面板(
Ctrl/Cmd + Shift + P) - 执行 "Dev Containers: Rebuild and Reopen in Container"
该命令会丢弃旧容器并基于最新配置重新构建,适合配置变更后使用。
容器内预置内容
工具与运行时
根据 Dockerfile 与 setup.sh 的实际内容,容器内预置了:
- Node.js 22:基础镜像为
mcr.microsoft.com/devcontainers/typescript-node:22,与仓库 package.json 声明的engines: "node": "22 || 24"兼容。 - Yarn 4.8.1:仓库 package.json 通过
packageManager字段固定,容器内无需额外安装,由仓库自身管理。 - Python 3 + 虚拟环境:
setup.sh在$HOME/venv创建虚拟环境,用于安装 TechDocs 工具链。 - MkDocs with TechDocs core:通过
python3 -m pip install mkdocs-techdocs-core安装,用于本地构建和预览 TechDocs 文档站。 - Chromium:由 Dockerfile 通过
apt-get install chromium安装,用于 Playwright 端到端测试(仓库根 package.json 中定义了test:e2e: playwright test)。 - 系统编译依赖:
build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev,这些是 Node 原生模块(如canvas相关依赖)编译所必需的。 - Git:基础镜像自带版本控制工具。
VS Code 扩展与设置
devcontainer.json 的 customizations.vscode 部分自动安装并配置了以下扩展:
- Prettier(
esbenp.prettier-vscode):代码格式化器,已启用保存时自动格式化(editor.formatOnSave: true),并设为默认格式化器。 - ESLint(
dbaeumer.vscode-eslint):JS/TS 代码检查器,对 JavaScript、JavaScript React、TypeScript、TypeScript React 四类文件生效。 - Backstage(
Intility.vscode-backstage):官方扩展,提供 Backstage 相关语法高亮与代码片段。
同时配置了以下编辑器级设置:
files.eol: "\n"与prettier.endOfLine: "lf":统一 LF 行尾,与仓库跨平台代码规范保持一致。editor.codeActionsOnSave:保存时自动执行source.fixAll与source.sortMembers,自动修复 lint 问题并排序成员。
环境变量注入
.devcontainer/devcontainer.env 通过 runArgs 中的 --env-file 注入容器环境,内容为:
NODE_OPTIONS=--no-node-snapshot
该变量禁用 Node.js 的启动快照(snapshot)特性,可规避部分开发场景下与调试器或文件监听相关的兼容问题。此外,runArgs 还包含 --sysctl net.ipv6.conf.all.disable_ipv6=1,用于在容器内禁用 IPv6,避免部分环境下 IPv6 解析导致的连接问题。
端口转发
devcontainer.json 通过 forwardPorts 声明自动转发以下端口:
| 端口 | 用途 | 转发行为 |
|---|---|---|
| 3000 | Frontend(前端应用) | 自动转发,静默模式,要求本地端口空闲 |
| 7007 | Backend API(后端 API) | 自动转发,静默模式,要求本地端口空闲 |
portsAttributes 中额外声明了 9464(metrics 指标端点),设置为静默自动转发;该端口也会在检测到服务监听时被编辑器自动转发。其中 requireLocalPort: true 意味着当本地对应端口被占用时会提示冲突。
在容器中启动 Backstage
容器就绪且依赖安装完成后,执行:
yarn start
该命令对应仓库根 package.json 中的 "start": "backstage-cli repo start",会同时启动:
- Frontend:http://localhost:3000
- Backend API:http://localhost:7007
注意:首次启动时,后端可能需要约一分钟才能完全就绪,浏览器中请等待后端就绪后刷新页面。前端应用的
baseUrl在 app-config.yaml 中配置为http://localhost:3000,与容器端口转发一致,无需额外修改。
常见问题排查
容器构建失败
- 确认 Docker Desktop 正在运行。
- 重建容器:命令面板 → "Dev Containers: Rebuild Container"。
- 检查 Docker 分配的资源是否充足(CPU、内存、磁盘空间需满足上文
hostRequirements)。
端口已被占用
若本地 3000 或 7007 端口已被其他进程占用:
- 停止占用这些端口的其他 Backstage 实例或服务(也可在 Docker Desktop 的 Ports 面板查看占用来源)。
- 重载 VS Code 窗口:命令面板 → "Developer: Reload Window"。
依赖未安装
若 yarn start 因缺少依赖而失败:
- 在终端中手动执行
yarn install。 - 或者重建容器,让 setup.sh 重新执行依赖安装。
性能问题
若容器运行缓慢:
- 调高 Docker Desktop 的资源分配(Settings → Resources),建议不低于 2 核 / 4GB。
- 确认 Docker 磁盘镜像未写满。
- Windows 用户请确保启用 WSL 2 以获得更优的 I/O 性能。
无法连接后端
若前端页面显示连接错误:
- 等待约一分钟让后端完全启动(观察终端日志)。
- 确认端口 7007 已正确转发(检查 VS Code 的 Ports 面板)。
- 刷新浏览器页面。
从源码层面理解容器配置
将文档与仓库实际配置对照,可以更清楚地理解 Dev Container 的完整工作链路:
- 构建阶段:devcontainer.json 的
build.dockerfile指向同目录Dockerfile,构建出基于 Node 22 并预装 Chromium 与编译依赖的镜像。 - 特性注入:
features引入common-utils(通用工具)与mkdocs(来自ghcr.io/devcontainers-extra),后者配合 setup 脚本补齐 TechDocs 所需的文档工具链。 - 创建后钩子:容器首次创建后执行
postCreateCommand,即 setup.sh,完成yarn install与 Python 虚拟环境、mkdocs-techdocs-core的安装。 - 运行参数:
runArgs注入环境变量并调整内核参数,规避 Node 快照与 IPv6 相关的潜在兼容问题。 - 开发体验:
customizations将格式化、lint、自动修复等规则一次性写入容器内的编辑器,使所有贡献者获得一致的编码环境——这与仓库根 package.json 中 lint-staged 定义的eslint --fix+prettier --write提交前校验流程互相呼应。
延伸阅读
- Dev Containers 规范:
containers.dev(本仓库配置遵循该规范) - VS Code Dev Containers 使用文档:VS Code 官方 Devcontainers 章节
- Backstage 贡献指南:仓库根目录的完整贡献流程
- Backstage 快速上手文档:容器环境就绪后的下一步操作指南