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](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

• 换句话说：Docker 明明在跑，但 VS Code + SAM CLI 坚持说"找不到 Docker" 。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

---

二、最终确认的根因（你这次遇到的）

• 你找到的最终原因是：在升级 Docker Desktop 之后，本地的 AWS SAM CLI 以及关系紧密的 AWS 工具链（如 VS Code 插件）版本没有同步升级，导致与新 Docker 版本的 API/行为不兼容 。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

• 升级 AWS SAM CLI 和 AWS 相关插件到最新版本后，错误提示消失，本地调试恢复正常。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)

• 升级方法：跟着官方文档重新下载安装包，会自动升级：https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html#install-sam-cli-instructions​

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

---

三、可能的原因总览（可用作分享中的 checklist）

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

3.1 Docker 本身真的没装 / 没启动

虽然看起来很基础，但在团队里经常是最真实的情况，可以简要提一下。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

• 未安装 Docker Desktop 或其他 Docker 引擎。

• Docker Desktop 已安装，但当前没有启动（托盘图标还在 starting / 未 running 状态）。

• 在 VS Code 集成终端中运行 docker ps 报"Cannot connect to the Docker daemon"等错误。

定位方式

• 打开 VS Code 集成终端，执行 docker ps、docker info。

• 如果这里都失败，基本优先检查 Docker 安装和启动状态。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

---

3.2 VS Code 所在环境与 Docker 不在同一个"世界"

这是第二类很常见的问题：你在 A 终端里能用 Docker，但 VS Code 使用的是 B 环境 。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

典型情形：

• 在 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](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

---

3.3 DOCKER_HOST / Docker context 配置把 SAM "带偏"

当使用过远程 Docker、Colima、Rancher Desktop 等工具时，很容易留下旧的 DOCKER_HOST 环境变量或非默认 Docker context。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

典型问题

• DOCKER_HOST 指向一个已经不存在或不可达的远程 Docker。

• 当前 Docker context 是某个远程/实验环境，而不是本地 Desktop。

• 用 docker ps 可能还显示得正常，但实际连的是某个奇怪的 host。

排查与修复

• 在 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](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

---

3.4 Docker 版本升级后，SAM CLI / 工具链版本太旧（你的实际案例）

这是你这次遇到的核心原因，也非常适合重点讲解。[stackoverflow](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

现象

• 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](https://stackoverflow.com/questions/50791354/running-aws-sam-projects-locally-get-error)​

解决方式

• 升级 AWS SAM CLI 到最新稳定版本。

• 升级 VS Code 中的 AWS Toolkit（以及如有需要的 AWS CLI 等依赖）。

• 升级后再次尝试本地运行 Lambda，问题消失。

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

---

四、推荐的排查顺序（可以直接投屏的一张 slide）

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

1. 确认 Docker 真的在 VS Code 环境里可用

   • 在 VS Code 集成终端执行 docker ps、docker info。

2. 检查环境是否一致

   • 是否在 WSL / Dev Container / 远程环境中？

   • 这些环境里是否也安装/映射了 Docker？

3. 检查 DOCKER_HOST 和 Docker context

   • 移除可疑的 DOCKER_HOST；确认当前 context 正确。

4. 检查版本兼容

   • Docker Desktop 是否刚升级？

   • sam --version 是否很老？

   • 升级 AWS SAM CLI、AWS Toolkit 等工具到最新版本。

5. 再次从 VS Code 中发起本地调试

   • 验证问题是否解决。