编辑

开发容器技巧和窍门

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

安装 Docker 的其他方法

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

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

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

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 任务栏项目并从上下文菜单中选择“切换到 Linux 容器...”来退出 LCOW 模式。
确保你的防火墙允许 Docker 设置共享驱动器。Docker 只需在两个机器本地 IP 之间建立连接，但某些防火墙软件仍可能阻止任何驱动器共享或所需的端口。有关解决此问题的后续步骤，请参阅这篇 Docker 知识库文章。

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

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

如果你仍然遇到问题，请参阅 Windows 版 Docker Desktop 疑难解答指南。

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

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

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

Windows

右键单击 Docker 任务栏项目，然后选择设置。
转到资源 > 文件共享，并选中你的源代码所在的驱动器。
如果你看到关于本地防火墙阻止共享操作的消息，请参阅这篇 Docker 知识库文章获取后续步骤。

macOS

单击 Docker 菜单栏项目，然后选择偏好设置。
转到资源 > 文件共享。确认包含你源代码的文件夹位于列出的共享文件夹之一中。

解决容器中的 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 Monitor 扩展。当安装在容器中时，它会在状态栏中提供有关容器容量的信息。

Resource use Status bar

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

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

如果你确定需要为容器分配更多机器容量，请按照以下步骤操作

右键单击 Docker 任务栏项目，然后选择设置 / 偏好设置。
转到高级，增加 CPU、内存或 Swap。
在 macOS 上，转到磁盘以增加 Docker 可以在你的机器上使用的磁盘空间量。在 Windows 上，此设置与其他设置一起位于“高级”下。

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

清理未使用的容器和映像

如果你看到 Docker 报错提示磁盘空间不足，通常可以通过清理未使用的容器和映像来解决此问题。有几种方法可以做到这一点

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

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

Remote Explorer screenshot

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

选项 2：使用 Docker 扩展

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

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

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

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

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

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

但是，由于 SSH 配置复杂性或其他限制，你的环境中可能无法正常工作。在这种情况下，可以使用 SSH 隧道作为备选方案。

将 SSH 隧道用作备选方案

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

请按照以下步骤操作

安装一个 OpenSSH 兼容的 SSH 客户端。
按照以下方式更新你的用户或工作区 settings.json 中的 Docker 扩展的 docker.environment 属性
```
"docker.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 属性在开发容器重建后保留用户配置文件（例如保留 shell 历史记录）。

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

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

高级容器配置技巧

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

扩展技巧

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

问题和反馈

报告问题

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

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

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

远程问题和反馈资源

我们还有许多其他远程资源

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

05/08/2025