编辑

开发容器使用技巧

本文包含了一些关于在不同环境中设置和运行开发容器扩展的技巧和窍门。

安装 Docker 的其他方法

您可以通过以下几种方式将 Docker 与开发容器扩展配合使用，包括：

本地安装 Docker。
在远程环境中安装 Docker。
在本地或远程安装其他兼容 Docker 的 CLI。
- 虽然其他 CLI 可能有效，但它们并未获得官方支持。请注意，连接到 Kubernetes 集群仅需要正确配置的 kubectl CLI。

您可以在备用 Docker 选项文档中了解更多信息。

自定义 AI 聊天回复

自定义指令允许您描述通用的指导方针或规则，以获取符合您特定编码实践和技术栈的回复。

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

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

Windows 版 Docker Desktop 技巧

Windows 版 Docker Desktop 在大多数设置中都能很好地工作，但有一些“陷阱”可能会导致问题。以下是一些避免它们的技巧：

考虑在 Windows 10 (2004+) 上使用新的 Docker WSL 2 后端。 如果您正在使用Docker Desktop 的 WSL 2 后端，您可以使用它打开 WSL 内部以及本地的文件夹。容器也在 Windows 和 WSL 内部共享，并且这个新引擎不易出现文件共享问题。详情请参阅快速入门。
切换出“Windows 上的 Linux 容器 (LCOW)”模式。 尽管默认禁用，但最新版本的 Docker 支持Windows 上的 Linux 容器 (LCOW)，它允许您同时使用 Windows 和 Linux 容器。然而，这是一个新功能，因此您可能会遇到问题，并且开发容器扩展目前仅支持 Linux 容器。您可以随时通过右键单击 Docker 任务栏图标并从上下文菜单中选择 Switch to Linux Containers... 来切换出 LCOW 模式。
确保您的防火墙允许 Docker 设置共享驱动器。 Docker 只需要在两个机器本地 IP 之间进行连接，但某些防火墙软件可能仍然会阻止任何驱动器共享或所需的端口。有关解决此问题的后续步骤，请参阅这篇 Docker 知识库文章。

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

共享驱动器时使用 AD 域帐户或本地管理员帐户。不要使用 AAD（基于电子邮件）帐户。 AAD（基于电子邮件）帐户存在众所周知的问题，如 Docker 问题 #132 和问题 #1352 中所述。如果您必须使用 AAD 帐户，请在您的机器上创建一个单独的本地管理员帐户，专门用于共享驱动器。按照此博客文章中的步骤进行设置。
坚持使用字母数字密码以避免驱动器共享问题。 当被要求在 Windows 上共享您的驱动器时，系统会提示您输入具有机器管理员权限的帐户的用户名和密码。如果系统警告您用户名或密码不正确，这可能是由于密码中包含特殊字符。例如，!、[ 和 ] 已知会导致问题。将密码更改为字母数字字符即可解决。有关详细信息，请参阅此关于Docker 卷挂载问题的议题。
使用您的 Docker ID 登录 Docker（而不是您的电子邮件）。 Docker CLI 仅支持使用您的 Docker ID，因此使用您的电子邮件可能会导致问题。详情请参阅 Docker 问题 #935。

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

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

请注意，使用Docker Desktop 的 WSL 2 引擎时，此步骤不是必需的。

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

Windows

右键单击 Docker 任务栏图标，然后选择 Settings。
转到 Resources > File Sharing，然后选中您的源代码所在的驱动器。
如果您看到关于本地防火墙阻止共享操作的消息，请参阅这篇 Docker KB 文章了解后续步骤。

macOS

单击 Docker 菜单栏图标，然后选择 Preferences。
转到 Resources > File Sharing。确认包含您的源代码的文件夹位于列出的共享文件夹之一中。

解决容器中 Git 行尾符问题（导致许多文件被修改）

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

通常，在您的仓库中添加或修改 .gitattributes 文件是解决此问题最可靠的方法。将此文件提交到源代码管理将有助于其他人，并允许您根据需要更改仓库行为。例如，将以下内容添加到仓库根目录的 .gitattributes 文件中，将强制所有内容为 LF，除了需要 CRLF 的 Windows 批处理文件：

* 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 push 或 sync 时挂起的问题

如果您使用 SSH 克隆 Git 仓库，并且您的 SSH 密钥有密码，则当远程运行时，VS Code 的 pull 和 sync 功能可能会挂起。

使用没有密码的 SSH 密钥，使用 HTTPS 克隆，或者从命令行运行 git push 以解决此问题。

解决缺少 Linux 依赖项的错误

某些扩展依赖于某些 Docker 镜像中找不到的库。请参阅容器文章，了解解决此问题的几种方法。

加快 Docker Desktop 中容器的速度

默认情况下，Docker Desktop 只为容器提供机器容量的一小部分。在大多数情况下，这已经足够了，但如果您正在做一些需要更多容量的事情，您可以增加内存、CPU 或磁盘使用量。

首先，尝试停止所有不再使用的正在运行的容器。

如果这不能解决您的问题，您可能需要查看 CPU 使用率是否确实是问题所在，或者是否有其他情况发生。一个简单的检查方法是安装资源监视器扩展。在容器中安装后，它会在状态栏中提供有关容器容量的信息。

Resource use Status bar

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

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

如果您确定需要为容器提供更多机器容量，请按照以下步骤操作：

右键单击 Docker 任务栏图标，然后选择 Settings / Preferences。
转到 Advanced 以增加 CPU、内存或交换空间。
在 macOS 上，转到 Disk 以增加 Docker 允许在您的机器上消耗的磁盘空间量。在 Windows 上，这位于 Advanced 下，与其他设置在一起。

最后，如果您的容器正在执行磁盘密集型操作，或者您只是希望获得更快的响应时间，请参阅提高容器磁盘性能以获取技巧。VS Code 的默认设置旨在方便和普遍支持，但可以进行优化。

清理未使用的容器和镜像

如果您看到 Docker 报告磁盘空间不足的错误，通常可以通过清理未使用的容器和镜像来解决。有几种方法可以做到这一点：

选项 1：使用远程资源管理器

您可以通过选择远程资源管理器，右键单击要删除的容器，然后选择删除容器来删除容器。

Remote Explorer screenshot

但是，这不会清理您可能已下载的任何镜像，这会使您的系统变得混乱。

选项 2：使用容器工具扩展

在 VS Code 中打开一个本地窗口（文件 > 新窗口）。
如果尚未安装，请从扩展视图中安装容器工具扩展。
然后，您可以转到容器资源管理器并展开容器或镜像节点，右键单击并选择删除容器/镜像。

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

打开一个本地终端/命令提示符（或在 VS Code 中使用本地窗口）。
键入 docker ps -a 以查看所有容器的列表。
从列表中键入 docker rm <Container ID> 以删除容器。
键入 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

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

选项 4：删除所有未运行的容器和镜像

打开一个本地终端/命令提示符（或在 VS Code 中使用本地窗口）。
键入 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：如果您不想删除容器或镜像，请在任何 apt 或 apt-get 命令之前将此行添加到 Dockerfile 中。它添加了 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 CLI 仅支持使用您的 Docker ID，因此使用您的电子邮件登录可能会导致问题。详情请参阅 Docker 问题 #935。

作为一种解决方法，请使用您的 Docker ID 而不是您的电子邮件登录 Docker。

macOS 上 Hyperkit 的高 CPU 利用率

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

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

在远程 Docker Machine 或 SSH 主机上的容器中开发文章介绍了在远程 Docker 主机上工作时如何设置 VS Code。这通常就像将容器工具扩展 containers.environment 属性在 settings.json 中或 DOCKER_HOST 环境变量设置为 ssh:// 或 tcp:// URI 一样简单。

但是，您可能会遇到由于 SSH 配置复杂性或其他限制导致此方法在您的环境中不起作用的情况。在这种情况下，SSH 隧道可以用作备用方案。

使用 SSH 隧道作为备用选项

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

请按照以下步骤操作：

安装支持 OpenSSH 的 SSH 客户端。
如下更新您的用户或工作区 settings.json 中的容器工具扩展 containers.environment 属性：
```
"containers.environment": {
    "DOCKER_HOST": "tcp://:23750"
}
```
从本地终端/PowerShell 运行以下命令（将 user@hostname 替换为远程用户和您的服务器主机名/IP）：
```
ssh -NL localhost:23750:/var/run/docker.sock user@hostname
```

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

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

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

在 SSH 主机（而不是本地）上使用编辑器（如 Vim、nano 或 Pico）打开 /etc/ssh/sshd_config。

添加设置 AllowStreamLocalForwarding yes。

重启 SSH 服务器（在 Ubuntu 上，运行 sudo systemctl restart sshd）。

重试。

持久化用户配置文件

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

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

上面的代码首先创建一个名为 profile 的命名卷，挂载到 /root，它将在重建后幸存。接下来，它创建一个匿名卷，挂载到 /root/.vscode-server，该卷在重建时被销毁，这允许 VS Code 重新安装扩展和点文件。

高级容器配置技巧

有关以下主题的信息，请参阅高级容器配置文章：

扩展提示

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

问题和反馈

报告问题

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

如果您在使用其他扩展远程时遇到问题（例如，其他扩展在远程环境中无法正常加载或安装），从远程扩展主机输出通道（输出：聚焦于输出视图）获取日志，并从下拉列表中选择日志（远程扩展主机）会很有帮助。

注意：如果您只看到日志（扩展主机），这是本地扩展主机，远程扩展主机未启动。这是因为日志通道仅在创建日志文件后才创建，因此如果远程扩展主机未启动，则未创建远程扩展主机日志文件，也不会显示在输出视图中。这仍然是包含在您的问题中的有用信息。

远程问题和反馈资源

我们还有各种其他远程资源：

在 Stack Overflow 上搜索。
添加功能请求或报告问题。

09/11/2025