Dev Container 配置轩辕镜像教程
轩辕镜像平台已支持 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
下面是一个示例配置，使用轩辕镜像，并安装 Poetry feature：
{
"name": "my-devcontainer",
"image": "xxx-ghcr.xuanyuan.run/devcontainers-extra/base:ubuntu-22.04",
"features": {
// 安装 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 基础镜像。
features：可以列出你需要的 Feature，例如 Poetry、Node.js、Python 等。
workspaceFolder：容器内的挂载工作目录。
54. 启动 Dev Container
在项目根目录运行：
devcontainer up --workspace-folder ~/myproject
CLI 会自动执行以下步骤：
- 拉取基础镜像（通过轩辕镜像源）
- 拉取并安装指定的 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 权限安装
- 检查网络连接
轩辕镜像配置手册
探索更多轩辕镜像的使用方法，找到最适合您系统的配置方式
登录仓库拉取
通过 Docker 登录认证访问私有仓库
Linux
在 Linux 系统配置镜像服务
Windows/Mac
在 Docker Desktop 配置镜像
Docker Compose
Docker Compose 项目配置
K8s Containerd
Kubernetes 集群配置 Containerd
K3s
K3s 轻量级 Kubernetes 镜像加速
宝塔面板
在宝塔面板一键配置镜像
群晖
Synology 群晖 NAS 配置
飞牛
飞牛 fnOS 系统配置镜像
极空间
极空间 NAS 系统配置服务
爱快路由
爱快 iKuai 路由系统配置
绿联
绿联 NAS 系统配置镜像
威联通
QNAP 威联通 NAS 配置
Podman
Podman 容器引擎配置
Singularity/Apptainer
HPC 科学计算容器配置
其他仓库配置
ghcr、Quay、nvcr 等镜像仓库
专属域名拉取
无需登录使用专属域名
需要其他帮助？请查看我们的 常见问题Docker 镜像访问常见问题解答 或 提交工单
镜像拉取常见问题
免费版仅支持 Docker Hub 访问，不承诺可用性和速度；专业版支持更多镜像源，保证可用性和稳定速度，提供优先客服响应。
专业版支持 docker.io、gcr.io、ghcr.io、registry.k8s.io、nvcr.io、quay.io、mcr.microsoft.com、docker.elastic.co 等；免费版仅支持 docker.io。
当返回 402 Payment Required 错误时，表示流量已耗尽，需要充值流量包以恢复服务。
通常由 Docker 版本过低导致，需要升级到 20.x 或更高版本以支持 V2 协议。
先检查 Docker 版本，版本过低则升级；版本正常则验证镜像信息是否正确。
使用 docker tag 命令为镜像打上新标签，去掉域名前缀，使镜像名称更简洁。
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
"Docker访问体验非常流畅，大镜像也能快速完成下载。"