我去年年底在一台刚装好 Ubuntu 24.04 的机器上折腾 AWS SAM CLI,本来以为跑两条命令就能完事,结果硬是被 Python 版本、PATH 环境变量、还有 Docker 权限这几个问题轮番教做人。事后我复盘了一下,其实不是 SAM 本身多难装,而是它依赖的链路过长,任何一个环节出了偏差,报错信息都容易把人带偏。这篇文章我打算把整个过程拆开揉碎,从装 AWS CLI 到跑通第一个 hello world,把每一步的原理和坑都说清楚,特别是那些官方文档里不会写的细节。
1. 安装前必须想明白的事:SAM 到底跑在什么上
很多人以为安装 AWS SAM 就是装一个命令行工具,其实它只是整个工具链的一个前端。真正干活的还有 AWS CLI、Docker、Python 运行时这几个组件。理解它们的分工,后面遇到问题才知道该查哪里。
1.1 SAM CLI、AWS CLI 和 Docker 的各自角色
SAM(Serverless Application Model)本质上是一个基于 CloudFormation 的模板规范和配套的 CLI 工具。模板文件让你用简洁的语法定义 Lambda 函数、API Gateway、DynamoDB 表等资源,CLI 工具负责把模板转换成 CloudFormation 的完整 JSON,然后帮你打包、部署。
这个转换依赖 AWS CLI 的底层能力,所以 AWS CLI 是必须的,两者版本之间还有兼容要求。
Docker 则是本地调试的基石。你可以用 sam local start-api 在本地起一个 API 服务,让 Lambda 函数在 Docker 容器里模拟运行。这样不用部署到云端就能测逻辑,也是 SAM 最实用的功能之一。如果你只打算直接 sam deploy 推送远程,不搞本地调试,Docker 可以暂时不装。但说实话,不装 Docker 的 SAM 跟折了一条腿差不多,还是建议一起装。
1.2 Ubuntu 版本和 Python 版本的影响
SAM CLI 本身是用 Python 写的,安装时它对 Python 版本有要求。较早的版本支持 Python 3.7,现在主流版本要求 Python 3.8 到 3.12 之间。Ubuntu 20.04 默认的 Python 3.8 能跑,Ubuntu 24.04 默认是 Python 3.12 也没问题。问题通常出在用户自己去折腾 Pyenv 或者系统里装了多个 Python 版本,导致 pip 装到了某个解释器下,PATH 里又是另一个解释器在前面。
我的建议是:用 Ubuntu 系统自带的 Python 版本,别用 PPA 或者编译安装的版本。系统自带的虽然旧,但跟系统组件兼容性最好,SAM 跑在上面反而不容易出事。如果你已经装了多版本 Python,安装前先用 python3 --version 确认默认解释器版本,再用 which python3 看它的路径,做到心里有数。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 前置工具安装:AWS CLI 与 Docker 的完整步骤
我习惯把前置工具先全部搞定,再装 SAM。这样每一步的依赖都是清晰的,出了问题也好定位。
2.1 官方推荐的 AWS CLI 安装方法
AWS CLI 目前分 v1 和 v2 两个大版本。SAM 虽然没有强制要求 v2,但强烈建议用 v2。因为 v2 是独立打包的二进制文件,不依赖系统的 Python 环境,也不容易被 pip 升级误伤。
安装 v2 的标准流程是这样:
bash复制cd /tmp
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
安装完成后验证一下:
bash复制aws --version
如果看到类似 aws-cli/2.17.13 Python/3.11.8 Linux/5.15.0-... 的输出,就说明 v2 装好了。这里需要留个心眼:报错里出现的 Python 版本只是 AWS CLI 自带的运行时,不是你系统的 Python,不用去纠结。
2.2 Docker 安装和当前用户的组权限配置
Docker 在 Ubuntu 上安装最省心的
