DevContainer Docker 镜像源配置教程
轩辕镜像平台已支持 Dev Containers，可以让你在国内环境快速构建开发容器，同时支持 Dev Container Features 安装（如 Poetry、Node.js、Python 工具等）。
1适用场景
本教程适用于以下开发场景：
21. 安装 Dev Containers CLI
Dev Containers CLI 是官方推荐的命令行工具，用于管理 Dev Container。
npm install -g @devcontainers/cli@latest
验证安装是否成功：
devcontainer --version
💡输出示例：0.80.1
如果你在国内环境，请确保 NPM 可以访问，必要时配置国内源：
npm config set registry https://registry.npmmirror.com
32. 准备工作空间
在你的项目根目录下创建 .devcontainer 文件夹，并新建 devcontainer.json 文件：
mkdir -p ~/myproject/.devcontainer cd ~/myproject/.devcontainer touch devcontainer.json
43. 配置 devcontainer.json
下面是一个示例配置，通过轩辕镜像加速拉取 MCR 上的官方基础镜像与 GHCR 上的 Feature，并安装 Poetry：
{
"name": "my-devcontainer",
// 基础镜像来源于 MCR（Microsoft Container Registry）
"image": "xxx-mcr.xuanyuan.run/devcontainers/base:ubuntu-22.04",
"features": {
// Feature 来源于 GHCR（GitHub Container Registry）
// 安装 Poetry 2.x
"xxx-ghcr.xuanyuan.run/devcontainers-extra/features/poetry:2": {}
},
// 可选：指定工作目录挂载一致性
"workspaceFolder": "/workspace",
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached"
}image：指定基础镜像。官方 Dev Container 基础镜像发布在 MCR（Microsoft Container Registry），通过轩辕镜像加速拉取，注意使用 xxx-mcr.xuanyuan.run 前缀。
features：可以列出你需要的 Feature，例如 Poetry、Node.js、Python 等。Feature 发布在 GHCR，使用 xxx-ghcr.xuanyuan.run 前缀。
⚠️注意区分 Registry 来源：官方 Dev Container 基础镜像（如 devcontainers/base）发布在 MCR（Microsoft Container Registry），需使用 xxx-mcr.xuanyuan.run；而 Feature（如 Poetry、Node.js）发布在 GHCR（GitHub Container Registry），需使用 xxx-ghcr.xuanyuan.run。VS Code / Dev Container CLI 文档中常省略 Registry 前缀，容易让人误以为基础镜像也在 GHCR 上，实际并非如此。
workspaceFolder：容器内的挂载工作目录。
54. 启动 Dev Container
在项目根目录运行：
devcontainer up --workspace-folder ~/myproject
CLI 会自动执行以下步骤：
- 从 MCR 拉取基础镜像（通过轩辕镜像加速）
- 拉取并安装指定的 Feature（如 Poetry）
- 挂载工作目录到容器
- 创建可交互开发环境
常用参数：
--remove-existing-container：如果容器已存在，先删除再重建--skip-post-create：跳过初始化命令--log-level trace：打印详细日志，方便排查下载或安装问题
65. 测试 Feature 是否安装成功
进入容器后，可以检查 Poetry 是否已安装：
poetry --version
输出示例：Poetry (version 2.0.18)
76. 高级用法：添加多个 Feature
在 devcontainer.json 中，可以同时添加多个 Feature：
"features": {
"xxx-ghcr.xuanyuan.run/devcontainers-extra/features/poetry:2": {},
"xxx-ghcr.xuanyuan.run/devcontainers-extra/features/node:20": {}
}CLI 会自动拉取并安装所有 Feature，无需手动执行 devcontainer features install。
87. 小贴士
调试命令：
devcontainer up --log-level trace --workspace-folder ~/myproject
💡这样，你就可以直接使用轩辕镜像，快速启动带有 Feature 的 Dev Container 开发环境。
9常见问题
- 网络连接问题
- NPM 源访问受限
- 权限不足
- 配置国内 NPM 源
- 使用 sudo 权限安装
- 检查网络连接
镜像拉取常见问题
使用与功能问题
错误码与失败问题
manifest unknown 错误：镜像不存在或标签错误
manifest unknown 错误
TLS/SSL 证书验证失败：Docker pull 时 HTTPS 证书错误
TLS 证书验证失败
DNS 解析超时：无法解析镜像仓库地址或连接超时
DNS 解析超时
410 Gone 错误：Docker 版本过低导致协议不兼容
410 错误：版本过低
402 Payment Required 错误：流量耗尽错误提示
402 错误：流量耗尽
401 UNAUTHORIZED 错误：身份认证失败或登录信息错误
身份认证失败错误
429 Too Many Requests 错误：请求频率超出专业版限制
429 限流错误
Docker login 凭证保存错误：Cannot autolaunch D-Bus（不影响登录）
凭证保存错误
账号 / 计费 / 权限
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
"Docker访问体验非常流畅，大镜像也能快速完成下载。"