应锁定python完整版本如"3.10.12"而非仅"3.10"，因补丁更新可能导致c扩展兼容问题；pip安装需加--no-cache-dir和--upgrade-strategy eager；pytest需指定测试路径、设置pythonpath或pip install -e .，并显式配置timeout-minutes。
直接用 actions/setup-python@v5 设置 Python 环境，配合 pip install -r requirements.txt 和 pytest 就能跑通基础流水线；但实际踩坑点不在“能不能跑”，而在“跑得对不对”——比如版本缓存失效、依赖冲突、测试路径错配。
为什么 setup-python 不能只写 python-version: "3.10"
GitHub 托管运行器的工具缓存里确实预装了常见版本，但写死字符串（如 "3.10"）会忽略补丁级差异。例如 "3.10" 可能解析为 3.10.12，而某次 CI 突然拉到 3.10.13，若项目依赖某个 C 扩展（如 numpy）的 wheel 包未及时适配新 patch，就会报 ImportError: undefined symbol。
- 稳妥写法是锁定完整版本：
python-version: "3.10.12" - 或使用语义化范围：
python-version: "3.10.x"（仅限明确接受补丁更新时） - 检查缓存是否命中：在
setup-python步骤后加run: python --version，确认实际加载版本
pip install 时哪些参数容易被忽略
默认 pip install -r requirements.txt 在 CI 中常因缓存或旧包残留导致行为不一致，尤其当 requirements.txt 里混用 == 和 ~= 时。
- 必须加
--no-cache-dir：避免复用本地构建缓存，确保干净安装 - 建议加
--upgrade-strategy eager：强制升级所有依赖到满足约束的最新兼容版，防止子依赖版本冲突 - 如果项目用
pyproject.toml+pip，需显式指定pip install --upgrade build再python -m build，否则setup.py可能被跳过
测试命令执行失败但日志没报错？先查这三处
pytest 在 CI 中静默失败很常见，不是代码问题，而是环境或路径配置偏差。
-
pytest默认只搜当前目录下的test_*.py或*_test.py，若测试文件在tests/下但没加-s tests/参数，会显示0 passed却不报错 - 没设
PYTHONPATH：当测试 import 本项目模块时，ModuleNotFoundError常因路径未包含项目根目录，应在install dependencies后加run: echo "$GITHUB_WORKSPACE" >> $PYTHONPATH或直接pip install -e . - 超时被杀：GitHub Actions 默认单步限时 60 分钟，但
pytest若含耗时 fixture（如启动数据库），可能触发TimeoutException而非 pytest 报错，需在run前加timeout-minutes: 15显式声明
真正麻烦的从来不是写完 workflow.yml，而是某天凌晨三点发现 pull_request 测试通过、push 到 main 却失败——往往是因为 on 触发条件里没统一 branches 配置，或者 secrets 权限没开给 fork 的 PR。这些细节不显眼，但改一次就得等十分钟重跑流水线。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
