编辑

开发容器技巧和窍门

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

安装 Docker 的其他方法

你可以通过以下几种方式将 Docker 与开发容器扩展一起使用，包括

本地安装的 Docker。
在远程环境中安装的 Docker。
其他符合 Docker 标准的 CLI，可本地或远程安装。
- 尽管其他 CLI 可能有效，但它们并非官方支持。请注意，附加到 Kubernetes 集群仅需要配置正确的 kubectl CLI。

你可以在其他 Docker 选项文档中了解更多信息。

自定义 AI 聊天响应

自定义指令使你能够描述通用的指导方针或规则，以获得符合你特定编码实践和技术栈的响应。

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

直接在 devcontainer.json 中添加 "github.copilot.chat.codeGeneration.instructions"
- 我们发布开发容器资源（例如镜像和Features），以便更轻松地创建和连接开发容器，并且我们现在在这些文件中包含了自定义指令。
- 此处是 Python Feature 中自定义指令的一个示例。
像在本地一样使用 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 KB 文章。

以下是一些适用于旧版本 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 的拉取和同步功能可能会挂起。

可以使用没有密码的 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

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

Remote Explorer screenshot

但是，这不会清理你可能下载的任何镜像，这些镜像可能会占用你的系统空间。

选项 2：使用 Container Tools 扩展

在 VS Code 中打开一个本地窗口（File > New Window）。
如果尚未安装，请从扩展视图中安装容器工具扩展。
然后你可以转到容器资源管理器，展开 Containers 或 Images 节点，右键单击并选择 Remove Container / Image。

选项 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 文件。

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

打开一个本地终端/命令提示符（或在 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 使用率。如果你在 Activity Monitor 中看到 com.docker.hyperkit 占用大量 CPU，而你的开发容器中几乎没有什么活动，则很可能遇到了此问题。关注Docker 问题以获取更新和修复。

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

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

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

使用 SSH 隧道作为备选选项

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

请按照以下步骤操作

安装一个兼容 OpenSSH 的 SSH 客户端。
按如下方式更新用户或工作区 settings.json 中 Container Tools 扩展的 containers.environment 属性
```
"containers.environment": {
    "DOCKER_HOST": "tcp://localhost: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 属性来持久化开发容器中的用户配置文件（保留外壳历史记录等），使其在重建后仍然存在。

    "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 获取开发容器扩展日志。

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

注意：如果你只看到 Log (Extension Host)，这是本地扩展主机，并且远程扩展主机未启动。这是因为只有在日志文件创建后才会创建日志通道，所以如果远程扩展主机未启动，则不会创建远程扩展主机日志文件，也不会在“输出”视图中显示。这仍然是对你报告问题有用的信息。

远程问题和反馈资源

我们有各种其他远程资源

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

06/12/2025