本地通过但ci失败的python单元测试，常源于环境变量差异或依赖版本隐性升级；本文以moto+dynamodb测试为例，详解如何定位aws_account_id与botocore 1.37.0的兼容性冲突，并提供可复现、可固化、可推广的工程化解决方案。
本地通过但ci失败的python单元测试，常源于环境变量差异或依赖版本隐性升级；本文以moto+dynamodb测试为例，详解如何定位aws_account_id与botocore 1.37.0的兼容性冲突，并提供可复现、可固化、可推广的工程化解决方案。
在Python工程化实践中，“本地能跑通 ≠ CI能过”是最具迷惑性的质量陷阱之一。你遇到的问题——moto模拟DynamoDB在CI中抛出 UnrecognizedClientException: The security token included in the request is invalid——并非moto失效，而是环境契约断裂的典型信号：CI环境注入了本地未设的 AWS_ACCOUNT_ID，触发了 botocore>=1.37.0 对DynamoDB endpoint URL生成逻辑的变更，而该变更与moto的mock机制尚未完全对齐。
? 根本原因解析
botocore 1.37.0（2024年中发布）引入了对 AWS_ACCOUNT_ID 等环境变量更积极的参与逻辑：当该变量存在时，botocore会尝试构造形如 https://dynamodb.us-east-1.amazonaws.com 的真实服务URL，而非默认回退到 http://localhost:5000（moto默认监听地址）。此时，即使 @mock_dynamodb 装饰器已启用，请求仍被发往无效的远程端点，导致认证失败。
验证方式极简：
# 本地复现CI行为 export AWS_ACCOUNT_ID="123456789012" python -m pytest tests/test_get_stream_config.py::TestDynamoDB::test_get_stream_config
若立即复现相同错误，即确认环境变量为根因。
✅ 工程化解决方案（三步闭环）
1️⃣ 【隔离】测试前显式清理敏感环境变量
在测试类或 conftest.py 中统一清除干扰项，避免“偶然成功”：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
import os
import unittest
from moto import mock_dynamodb
class TestDynamoDB(unittest.TestCase):
def setUp(self):
# 强制清理可能干扰moto的AWS环境变量
for key in list(os.environ.keys()):
if key.startswith("AWS_") and key not in {"AWS_DEFAULT_REGION"}:
os.environ.pop(key, None)
self.mock = mock_dynamodb()
self.mock.start()
# ... 后续创建表逻辑
2️⃣ 【锁定】在 pyproject.toml 或 requirements.txt 中硬性约束版本
避免CI因缓存或镜像源拉取到不兼容版本：
# pyproject.toml [project.dependencies] moto = "^4.2.0" botocore = "~=1.36.0" # 使用兼容范围，而非固定版本 boto3 = "^1.34.0"
✅ 为什么不用
==1.36.1？
固定版本易引发后续安全更新阻塞；~=1.36.0表示允许1.36.x任意小版本升级（含安全补丁），但禁止跨1.37大版本跃迁。
3️⃣ 【验证】CI流水线中加入环境一致性检查
在 .gitlab-ci.yml 或 .github/workflows/test.yml 的 before_script 中添加断言：
before_script:
- python -c "import botocore; assert botocore.__version__.startswith('1.36'), f'botocore version {botocore.__version__} violates constraint 1.36.x'"
- python -c "import os; assert 'AWS_ACCOUNT_ID' not in os.environ, 'AWS_ACCOUNT_ID must be unset for moto tests'"
⚠️ 关键注意事项
-
不要依赖
@mock_dynamodb的类级装饰器：你代码中mock_dynamodb2 = mock_dynamodb()是类属性，在类加载时即初始化，此时setUp尚未执行，环境变量清理无效。务必改用实例级self.mock = mock_dynamodb()+self.mock.start()模式。 -
moto版本需同步升级：moto>=4.2.0已适配botocore 1.37+的部分变更，若长期无法降级botocore，应优先升级moto并查阅其 Changelog。 -
CI环境≠开发环境：GitLab Runner 或 GitHub Actions 默认启用更多系统级环境变量（如
CI=true,GITHUB_ACTIONS），需审计所有env:块和 runner 配置，确保无意外注入。
? 总结
这个看似偶然的CI失败，本质是环境不可控性暴露了测试脆弱性。真正的工程化不是让测试“恰好通过”，而是：
✅ 显式声明环境假设（如“AWS_ACCOUNT_ID 必须为空”）；
✅ 用工具链强制约束（版本锁+运行时断言）；
✅ 将本地可复现性作为CI通过的前置条件。
当你的测试能在任意干净Python环境中一键复现CI行为时，质量才真正可控。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
