Docker 升级后 VS Code 本地调试 AWS Lambda 报「Running AWS SAM projects locally requires Docker」的那些坑与排查思路

一、问题场景描述

在 VS Code 中使用 AWS Toolkit 本地调试 Lambda（基于 AWS SAM 项目）时，点击本地运行/调试，出现提示：

"Running AWS SAM projects locally requires Docker. Have you got it installed and running?"
实际情况是：本地已经安装并运行 Docker Desktop，使用命令行执行 docker ps、docker info 等都正常，容器环境可用。[stackoverflow]
换句话说：Docker 明明在跑，但 VS Code + SAM CLI 坚持说"找不到 Docker" 。[stackoverflow]

你找到的最终原因是：在升级 Docker Desktop 之后，本地的 AWS SAM CLI 以及关系紧密的 AWS 工具链（如 VS Code 插件）版本没有同步升级，导致与新 Docker 版本的 API/行为不兼容 。[stackoverflow]
升级 AWS SAM CLI 和 AWS 相关插件到最新版本后，错误提示消失，本地调试恢复正常。[stackoverflow]
升级方法：跟着官方文档重新下载安装包，会自动升级：https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html#install-sam-cli-instructions

这一点可以作为你分享里的"主线故事"------"隐形的版本兼容问题"。

你可以按"从最基础到偏高级"的顺序介绍，帮助听众形成排查思路。

虽然看起来很基础，但在团队里经常是最真实的情况，可以简要提一下。[stackoverflow]

定位方式

这是第二类很常见的问题：你在 A 终端里能用 Docker，但 VS Code 使用的是 B 环境 。[stackoverflow]

典型情形：

在 Windows 上用 WSL 打开工程，而 Docker Desktop 只在 Windows 环境可见；VS Code 的调试在 WSL 里跑，WSL 内没有可用的 Docker socket。
使用 Dev Container / Remote-SSH / Remote-WSL 等远程开发模式，但容器/远程环境内部没有 Docker 或没有映射 Docker socket。
手动开终端时用的是一个 shell profile，设置了一些变量或 alias，而 VS Code 集成终端没有加载同样的配置。

定位方式

一律在 VS Code 集成终端中执行：docker ps、sam local invoke，看输出和普通终端是否一致。
如果普通终端 OK，VS Code 里失败，就可以讲：

"问题在于 VS Code 运行 SAM CLI 的环境，与我平时用的终端环境不一样。"[stackoverflow]

当使用过远程 Docker、Colima、Rancher Desktop 等工具时，很容易留下旧的 DOCKER_HOST 环境变量或非默认 Docker context。[stackoverflow]

典型问题

排查与修复

在 VS Code 集成终端中查看环境变量：
- Linux/macOS: env | grep DOCKER_HOST
- PowerShell: Get-ChildItem Env:DOCKER_HOST
如果有值，可以尝试临时 unset / Remove-Item Env:DOCKER_HOST，再试一次本地调试。
查看 Docker context：docker context ls，确认当前 active 的 context 是否是预期的本地环境。
若问题解决，可以在分享中强调：

"遇到 Docker 明明在跑却被认为'不可用'时，记得检查 DOCKER_HOST 和 docker context。"[stackoverflow]

这是你这次遇到的核心原因，也非常适合重点讲解。[stackoverflow]

现象

Docker Desktop 升级到新版本之后，docker ps 等命令都正常。
但通过 VS Code（AWS Toolkit）点击本地运行 Lambda，提示仍然是 "Running AWS SAM projects locally requires Docker..."。
手动在终端执行 sam local invoke 或 sam local start-api 可能也会报类似"Docker 不可达"或 API 相关的错误。

原因

老版本的 AWS SAM CLI 内部依赖的 Docker 客户端库，对新 Docker API 或某些行为不兼容。
VS Code 的 AWS Toolkit 也有对 SAM CLI 或 Docker 的版本要求，如果太旧，检测逻辑会失败。
结果就是：Docker 实际可用，但健康检查阶段就"挂了"，于是前端统一抛出"需要安装 Docker"这种误导性的错误信息 。[stackoverflow]

解决方式

这一段可以作为你分享里"真正踩坑"的部分，强调"Docker 升级后别忘了升级 SAM / 工具链"。

你可以整理成一个"故障排查流程"：

确认 Docker 真的在 VS Code 环境里可用
- 在 VS Code 集成终端执行 docker ps、docker info。
检查环境是否一致
- 是否在 WSL / Dev Container / 远程环境中？
- 这些环境里是否也安装/映射了 Docker？
检查 DOCKER_HOST 和 Docker context
- 移除可疑的 DOCKER_HOST；确认当前 context 正确。
检查版本兼容
- Docker Desktop 是否刚升级？
- sam --version 是否很老？
- 升级 AWS SAM CLI、AWS Toolkit 等工具到最新版本。
再次从 VS Code 中发起本地调试
- 验证问题是否解决。