# DevContainer Docker 镜像源配置教程

> 在线版：https://xuanyuan.cloud/usage/devcontainer

轩辕镜像平台已支持 Dev Containers，可以让你在国内环境快速构建开发容器，同时支持 Dev Container Features 安装（如 Poetry、Node.js、Python 工具等）。

## 目录

- [1. 适用场景](#1-适用场景)
- [2. 安装 Dev Containers CLI](#2-安装-dev-containers-cli)
- [3. 准备工作空间](#3-准备工作空间)
- [4. 配置 devcontainer.json](#4-配置-devcontainerjson)
- [5. 启动 Dev Container](#5-启动-dev-container)
- [6. 测试 Feature 是否安装成功](#6-测试-feature-是否安装成功)
- [7. 高级用法：添加多个 Feature](#7-高级用法添加多个-feature)
- [8. 小贴士](#8-小贴士)
- [9. 常见问题](#9-常见问题)

## 1. 适用场景

本教程适用于以下开发场景：

| 开发环境 | 是否支持 | 说明 |
|---------|---------|------|
| VS Code Dev Containers | ✅ 完全支持 | 通过 Dev Container CLI 管理 |
| 命令行环境 | ✅ 完全支持 | 直接使用 CLI 工具 |
| Dev Container Features | ✅ 完全支持 | Poetry、Node.js、Python 等 |

## 2. 安装 Dev Containers CLI

Dev Containers CLI 是官方推荐的命令行工具，用于管理 Dev Container。

```bash
npm install -g @devcontainers/cli@latest
```

验证安装是否成功：

```bash
devcontainer --version
```

> **提示**：输出示例：`0.80.1`

如果你在国内环境，请确保 NPM 可以访问，必要时配置国内源：

```bash
npm config set registry https://registry.npmmirror.com
```

## 3. 准备工作空间

在你的项目根目录下创建 .devcontainer 文件夹，并新建 devcontainer.json 文件：

```bash
mkdir -p ~/myproject/.devcontainer
cd ~/myproject/.devcontainer
touch devcontainer.json
```

## 4. 配置 devcontainer.json

下面是一个示例配置，通过轩辕镜像加速拉取 MCR 上的官方基础镜像与 GHCR 上的 Feature，并安装 Poetry：

```json
{
  "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：**容器内的挂载工作目录。

## 5. 启动 Dev Container

在项目根目录运行：

```bash
devcontainer up --workspace-folder ~/myproject
```

CLI 会自动执行以下步骤：

- 从 MCR 拉取基础镜像（通过轩辕镜像加速）
- 拉取并安装指定的 Feature（如 Poetry）
- 挂载工作目录到容器
- 创建可交互开发环境

**常用参数：**

- `--remove-existing-container`：如果容器已存在，先删除再重建
- `--skip-post-create`：跳过初始化命令
- `--log-level trace`：打印详细日志，方便排查下载或安装问题

## 6. 测试 Feature 是否安装成功

进入容器后，可以检查 Poetry 是否已安装：

```bash
poetry --version
```

> **提示**：输出示例：`Poetry (version 2.0.18)`

## 7. 高级用法：添加多个 Feature

在 devcontainer.json 中，可以同时添加多个 Feature：

```json
"features": {
  "***-ghcr.xuanyuan.run/devcontainers-extra/features/poetry:2": {},
  "***-ghcr.xuanyuan.run/devcontainers-extra/features/node:20": {}
}
```

CLI 会自动拉取并安装所有 Feature，无需手动执行 devcontainer features install。

## 8. 小贴士

调试命令：

```bash
devcontainer up --log-level trace --workspace-folder ~/myproject
```

> **提示**：这样，你就可以直接使用轩辕镜像，快速启动带有 Feature 的 Dev Container 开发环境。

## 9. 常见问题

| 问题描述 | 可能原因 | 解决方法 |
|---------|---------|---------|
| CLI 安装失败 | 网络连接问题；NPM 源访问受限；权限不足 | 配置国内 NPM 源；使用 sudo 权限安装；检查网络连接 |
| 镜像拉取失败 | 轩辕镜像地址配置错误或流量不足 | 检查镜像地址正确性，前往[充值页面](https://xuanyuan.cloud/recharge)充值流量包 |
| Feature 安装失败 | Feature 版本不兼容或网络问题 | 检查 Feature 版本兼容性，使用 --log-level trace 查看详细错误 |