探索智能体开发 -

Dev Containers 使用技巧与提示

本文包含了一些帮助你在不同环境中运行 Dev Containers 扩展的提示和技巧。

安装 Docker 的其他方式

你可以通过多种方式将 Docker 与 Dev Containers 扩展配合使用，包括：

  • 本地安装 Docker。
  • 安装在远程环境中的 Docker。
  • 其他兼容 Docker 的 CLI 工具（本地或远程安装）。

你可以在 Docker 替代方案文档中了解更多信息。

自定义 AI 聊天回复

自定义指令使你能够描述通用的准则或规则，从而获得符合你特定编码实践和技术栈的回复。

你可以将自定义指令与开发容器配合使用，以便为 Copilot 提供有关你所连接的开发容器类型的更多信息（例如安装了哪种语言或工具链）。你可以通过以下几种方式实现：

  • 直接在 devcontainer.json 中添加 "github.copilot.chat.codeGeneration.instructions"
    • 我们发布了开发容器资源（如 镜像 和 功能 (Features)）以简化创建和连接开发容器的过程，并且我们现在在这些文件中包含了自定义指令。
    • 这里是一个在 Python 功能中使用自定义指令的示例。
  • 像在本地一样使用 copilot-instructions.md 文件

Windows 版 Docker Desktop 使用技巧

Docker Desktop for Windows 在大多数设置下都能良好运行，但仍有一些“陷阱”可能会导致问题。以下是一些避免这些问题的提示：

  1. 考虑在 Windows 10 (2004+) 上使用新的 Docker WSL 2 后端。 如果你正在使用 Docker Desktop 的 WSL 2 后端，你可以用它来打开 WSL 内部或本地的文件夹。此外，容器会在 Windows 和 WSL 内部共享，这种新引擎较少受到文件共享问题的影响。详情请参阅快速入门。

  2. 退出“Linux Containers on Windows (LCOW)”模式。 虽然默认情况下处于禁用状态，但 Docker 的较新版本支持 Linux Containers on Windows (LCOW)，允许你同时使用 Windows 和 Linux 容器。但由于这是一项新功能，你可能会遇到问题，且 Dev Containers 扩展目前仅支持 Linux 容器。你可以随时右键点击任务栏上的 Docker 图标并从上下文菜单中选择 Switch to Linux Containers... 来退出 LCOW 模式。

  3. 确保防火墙允许 Docker 设置共享驱动器。 Docker 只需要在两个本地机器 IP 之间连接，但某些防火墙软件仍可能阻止任何驱动器共享或必要的端口。

以下是一些适用于旧版 Docker for Windows 但现在应该已解决的提示。如果你因可能的回归而遇到奇怪的行为，这些提示曾在过去解决过问题。

  1. 在共享驱动器时，使用 AD 域帐户或本地管理员帐户。不要使用 AAD（基于电子邮件的）帐户。 AAD 帐户存在已知问题，详见 Docker 问题 #132 和 问题 #1352。如果你必须使用 AAD 帐户，请在你的机器上创建一个纯粹用于共享驱动器的单独本地管理员帐户。按照此博客文章中的步骤进行设置。

  2. 坚持使用字母数字密码以避免驱动器共享问题。 当系统要求你在 Windows 上共享驱动器时，会提示你输入具有管理权限的帐户的用户名和密码。如果你收到有关用户名或密码错误的警告，可能是因为密码中包含特殊字符。例如，!、[ 和 ] 是已知的引起问题的字符。将密码更改为字母数字字符即可解决。有关详细信息，请参阅关于 Docker 卷挂载问题的讨论。

  3. 使用你的 Docker ID 登录 Docker（不要使用你的电子邮件）。 Docker CLI 仅支持使用 Docker ID，因此使用电子邮件登录可能会导致问题。详情请参阅 Docker 问题 #935。

如果你仍然遇到问题，请参阅 Docker Desktop for Windows 故障排除指南。

在 Docker Desktop 中启用文件共享

VS Code Dev Containers 扩展仅能在你的代码位于与 Docker 共享的文件夹或驱动器中时，自动将源代码挂载到容器中。如果你从非共享位置打开开发容器，容器将成功启动，但工作区将为空。

请注意，在使用 Docker Desktop 的 WSL 2 引擎时，此步骤不需要执行。

要更改 Docker 的驱动器和文件夹共享设置：

Windows

  1. 右键点击任务栏上的 Docker 图标并选择 Settings。
  2. 转到 Resources > File Sharing 并勾选包含你源代码的驱动器。
  3. 如果你看到有关本地防火墙阻止共享操作的消息，请参阅这篇 Docker 知识库文章了解后续步骤。

macOS

  1. 点击菜单栏上的 Docker 图标并选择 Preferences。
  2. 转到 Resources > File Sharing。确认包含源代码的文件夹在列出的共享文件夹中。

解决容器内 Git 换行符问题（导致大量文件被修改）

由于 Windows 和 Linux 使用不同的默认换行符，Git 可能会报告大量除了换行符外没有其他差异的被修改文件。为了防止这种情况，你可以通过 .gitattributes 文件或在 Windows 端进行全局设置来禁用换行符转换。

通常，在存储库中添加或修改 .gitattributes 文件是解决此问题最可靠的方法。将此文件提交到源代码管理有助于他人使用，并允许你根据存储库按需设置行为。例如，在存储库根目录下将以下内容添加到 .gitattributes 文件中，将强制所有内容为 LF，Windows 批处理文件除外（它们需要 CRLF）：

* text=auto eol=lf
*.{cmd,[cC][mM][dD]} text eol=crlf
*.{bat,[bB][aA][tT]} text eol=crlf

请注意，这适用于 Git v2.10+，因此如果你遇到问题，请确保安装了较新版本的 Git 客户端。你可以将存储库中需要 CRLF 的其他文件类型添加到同一文件中。

如果你仍希望始终上传 Unix 风格的换行符 (LF)，可以使用 input 选项。

git config --global core.autocrlf input

如果你希望完全禁用换行符转换，请改为运行以下命令：

git config --global core.autocrlf false

最后，你可能需要重新克隆存储库以使这些设置生效。

在使用 Docker Compose 时避免在容器内设置 Git

有关解决此问题的信息，请参阅主要容器文章中的 与容器共享 Git 凭据。

解决从容器进行 Git 推送或同步时的卡顿问题

如果你使用 SSH 克隆 Git 存储库且你的 SSH 密钥有密码短语，VS Code 的拉取和同步功能在远程运行时可能会卡住。

请使用没有密码短语的 SSH 密钥，改用 HTTPS 克隆，或者从命令行运行 git push 以绕过此问题。

解决缺少 Linux 依赖项的错误

某些扩展依赖于特定 Docker 镜像中不存在的库。请参阅 容器 文章中关于解决此问题的几种方案。

加速 Docker Desktop 中的容器

默认情况下，Docker Desktop 仅为容器提供机器容量的一小部分。在大多数情况下这已足够，但如果你执行的任务需要更多容量，可以增加内存、CPU 或磁盘使用量。

首先，尝试 停止不再使用的运行中容器。

如果这不能解决问题，你可能需要检查 CPU 使用率是否确实是问题所在。一种简单的方法是安装 Resource Monitor 扩展。在容器内安装后，它会在状态栏中提供容器的容量信息。

Resource use Status bar

如果你希望始终安装此扩展，请将其添加到你的 settings.json 中：

"dev.containers.defaultExtensions": [
    "mutantdino.resourcemonitor"
]

如果你确定需要为容器分配更多机器容量，请执行以下步骤：

  1. 右键点击任务栏上的 Docker 图标并选择 Settings / Preferences。
  2. 转到 Advanced 以增加 CPU、内存或 Swap（交换空间）。
  3. 在 macOS 上，转到 Disk 以增加 Docker 在机器上允许占用的磁盘空间。在 Windows 上，这位于 Advanced 设置中。

最后，如果你的容器在进行磁盘密集型操作，或者你只是想获得更快的响应时间，请参阅 提高容器磁盘性能 了解技巧。VS Code 的默认设置旨在兼顾便利性和通用支持，但可以进行优化。

清理未使用的容器和镜像

如果你看到 Docker 报告磁盘空间不足的错误，通常可以通过清理未使用的容器和镜像来解决。有几种方法可以执行此操作：

方案 1：使用远程资源管理器 (Remote Explorer)

你可以通过选择 Remote Explorer，右键点击要删除的容器，然后选择 Remove Container 来删除容器。

Remote Explorer screenshot

然而，这不会清理你可能已下载的镜像，这些镜像可能会占用系统空间。

方案 2：使用 Container Tools 扩展

  1. 在 VS Code 中打开一个本地窗口（File > New Window）。

  2. 如果尚未安装，请从扩展视图中安装 Container Tools 扩展。

  3. 然后你可以转到 Container Explorer 并展开 Containers 或 Images 节点，右键点击并选择 Remove Container / Image。

    Container Explorer screenshot

方案 3：使用 Docker CLI 选择要删除的容器

  1. 打开本地终端/命令提示符（或在 VS Code 中使用本地窗口）。
  2. 输入 docker ps -a 查看所有容器的列表。
  3. 从该列表中输入 docker rm <Container ID> 以删除特定容器。
  4. 输入 docker image prune 以删除所有未使用的镜像。

如果 docker ps 提供的信息不足以识别要删除的容器，以下命令将列出所有由 VS Code 管理的开发容器以及用于生成它们的文件夹。

docker ps -a --filter="label=vsch.quality" --format "table {{.ID}}\t{{.Status}}\t{{.Image}}\tvscode-{{.Label \"vsch.quality\"}}\t{{.Label \"vsch.local.folder\"}}"

方案 4：使用 Docker Compose

  1. 打开本地终端/命令提示符（或在 VS Code 中使用本地窗口）。
  2. 进入包含 docker-compose.yml 文件的目录。
  3. 输入 docker-compose down 以停止并删除容器。如果你有多个 Docker Compose 文件，可以使用 -f 参数指定额外的 Docker Compose 文件。

方案 5：删除所有非运行中的容器和镜像

  1. 打开本地终端/命令提示符（或在 VS Code 中使用本地窗口）。
  2. 输入 docker system prune --all。

解决 Debian 8 镜像的 Dockerfile 构建失败问题

当构建使用基于 Debian 8/Jessie 的镜像（例如 node:8 镜像的较旧版本）的容器时，你可能会遇到以下错误：

...
W: Failed to fetch http://deb.debian.org/debian/dists/jessie-updates/InRelease  Unable to find expected entry 'main/binary-amd64/Packages' in Release file (Wrong sources.list entry or malformed file)
E: Some index files failed to download. They have been ignored, or old ones used instead.
...

这是一个广为人知的问题，原因是 Debian 8 已被“归档”。较新版本的镜像通常通过升级到 Debian 9/Stretch 来解决此问题。

有两种方法可以解决此错误：

  • 方案 1：删除所有依赖于该镜像的容器，移除镜像，然后尝试重新构建。这将下载一个未受该问题影响的更新镜像。详情请参阅 清理未使用的容器和镜像。

  • 方案 2：如果你不想删除容器或镜像，请在 Dockerfile 中的任何 apt 或 apt-get 命令之前添加此行。它会为 Jessie 添加所需的源列表：

    # Add archived sources to source list if base image uses Debian 8 / Jessie
RUN cat /etc/*-release | grep -q jessie && printf "deb http://archive.debian.org/debian/ jessie main\ndeb-src http://archive.debian.org/debian/ jessie main\ndeb http://security.debian.org jessie/updates main\ndeb-src http://security.debian.org jessie/updates main" > /etc/apt/sources.list

解决使用电子邮箱登录 Docker Hub 时的错误

Docker CLI 仅支持使用 Docker ID，因此使用电子邮件登录可能会导致问题。详情请参阅 Docker 问题 #935。

作为临时措施，请使用 Docker ID 而不是电子邮件登录 Docker。

macOS 上 Hyperkit CPU 占用率过高

Docker for Mac 存在一个已知问题，可能会导致 CPU 飙升。特别是在监视文件和构建时。如果你在开发容器中几乎没有操作时，在活动监视器中看到 com.docker.hyperkit 的 CPU 使用率很高，则很可能遇到了此问题。请关注 Docker 问题页面以获取更新和修复。

使用 SSH 隧道连接到远程 Docker 主机

在远程 Docker Machine 或 SSH 主机上的容器内开发文章介绍了如何在使用远程 Docker 主机时设置 VS Code。通常只需将 Container Tools 扩展 的 containers.environment 属性在 settings.json 中设置，或将 DOCKER_HOST 环境变量设置为 ssh:// 或 tcp:// URI 即可。

但是，由于 SSH 配置复杂或其他限制，你可能会在环境中遇到此方法无效的情况。在这种情况下，可以使用 SSH 隧道作为后备方案。

使用 SSH 隧道作为后备选项

你可以设置 SSH 隧道并将 Docker 套接字从远程主机转发到本地机器。

请按照以下步骤操作：

  1. 安装 OpenSSH 兼容的 SSH 客户端。

  2. 在你的用户或工作区 settings.json 中更新 Container Tools 扩展 的 containers.environment 属性，如下所示：

    "containers.environment": {
    "DOCKER_HOST": "tcp://:23750"
}

  3. 从本地终端 / PowerShell 运行以下命令（将 user@hostname 替换为你服务器的远程用户和主机名 / IP）：

    ssh -NL localhost:23750:/var/run/docker.sock user@hostname

VS Code 现在将能够 附加到远程主机上的任何运行中容器。你还可以 使用专门的本地 devcontainer.json 文件来创建 / 连接到远程开发容器。

完成后，在终端 / PowerShell 中按 Ctrl+C 关闭隧道。

注意： 如果 ssh 命令失败，你可能需要在 SSH 主机上启用 AllowStreamLocalForwarding。

  1. 在 SSH 主机（非本地）上，使用编辑器（如 Vim、nano 或 Pico）打开 /etc/ssh/sshd_config。
  2. 添加设置 AllowStreamLocalForwarding yes。
  3. 重启 SSH 服务器（在 Ubuntu 上，运行 sudo systemctl restart sshd）。
  4. 重试。

持久化用户配置

你可以使用 mounts 属性在开发容器中持久化用户配置文件（以保留 shell 历史记录等内容），使其在重新构建后依然存在。

    "mounts": [
        "source=profile,target=/root,type=volume",
        "target=/root/.vscode-server,type=volume"
    ],

上述代码首先创建一个名为 profile 的挂载到 /root 的命名卷，该卷在重建后仍然存在。接着创建一个挂载到 /root/.vscode-server 的匿名卷，该卷在重建时会被销毁，这允许 VS Code 在重建后重新安装扩展和 dotfiles。

高级容器配置技巧

请参阅 高级容器配置 文章了解以下主题的信息：

扩展功能使用技巧

虽然许多扩展可以直接使用，但有些问题可能会导致某些功能无法按预期工作。在某些情况下，你可以使用其他命令来绕过问题，而在其他情况下，则需要修改扩展。 远程扩展提示 部分提供了常见问题的快速参考和解决技巧。你还可以参考有关 支持远程开发 的主扩展文章，获取有关修改扩展以支持远程扩展主机的深入指南。

问题和反馈

报告问题

如果你在使用 Dev Containers 扩展时遇到问题，收集正确的日志非常重要，这样我们将能够帮助你 诊断问题。你可以通过 Dev Containers: Show Container Log 获取 Dev Containers 扩展日志。

如果你在使用其他扩展时遇到远程问题（例如，其他扩展在远程上下文中无法加载或安装），从 Remote Extension Host 输出通道（Output: Focus on Output View）获取日志会很有帮助，请从下拉菜单中选择 Log (Remote Extension Host)。

注意：如果你只看到 Log (Extension Host)，这表示本地扩展主机，且远程扩展主机未启动。这是因为日志通道仅在日志文件创建后才会生成，如果远程扩展主机未启动，则不会创建远程扩展主机日志文件，因此输出视图中不会显示该选项。不过，在提交问题时包含这些信息仍然很有用。

远程相关问题与反馈资源

我们有多种其他远程资源可供参考：

4/8/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.