让 AI 帮你使用轩辕镜像？ · 展开查看说明 · 点击收起说明
如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。
只需在 AI 对话中先发送下面这句话即可：
请先完整阅读并严格遵守以下文档中的全部规则与要求：
https://xuanyuan.cloud/agents.md
在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。查看 agents.md 用法指南与完整示范。国内用户首推 元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。 若 AI 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
DevContainer Docker 镜像源配置教程
教程简介
适用场景
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": "***-mcr.xuanyuan.run/devcontainers/base:ubuntu-22.04",
"features": {
// Feature 来源于 GHCR（GitHub Container Registry）
// 安装 Poetry 2.x
"***-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），通过轩辕镜像加速拉取，注意使用 ***-mcr.xuanyuan.run 前缀。
features：可以列出你需要的 Feature，例如 Poetry、Node.js、Python 等。Feature 发布在 GHCR，使用 ***-ghcr.xuanyuan.run 前缀。
⚠️注意区分 Registry 来源：官方 Dev Container 基础镜像（如 devcontainers/base）发布在 MCR（Microsoft Container Registry），需使用 ***-mcr.xuanyuan.run；而 Feature（如 Poetry、Node.js）发布在 GHCR（GitHub Container Registry），需使用 ***-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": {
"***-ghcr.xuanyuan.run/devcontainers-extra/features/poetry:2": {},
"***-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 权限安装
- 检查网络连接
镜像拉取常见问题
功能
错误码
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
"Docker访问体验非常流畅，大镜像也能快速完成下载。"