我以前带过一个Python项目组第一版CI流水线看着挺像样——lint、单测、覆盖率、打包、部署全齐了代码一推就自动跑。结果真正上线那晚直接翻车测试环境里跑得好好的接口一到生产就报依赖版本错误排查到凌晨两点才发现流水线压根没做依赖锁定每次pip install都在装当前最新版本地、CI、生产三个环境各装各的。后来我花了两个星期把CI/CD for Python这套东西全部重做了一遍才彻底治好了这个顽疾。这篇文章就是我当时重做流水线的完整记录适合正在从手动本地跑一下再部署往自动化流水线升级的Python开发者。无论你是写Django/Flask/FastAPI的Web应用还是做爬虫脚本、数据处理工具、被分发给其他人安装的第三方库只要你希望改完代码机器自动帮我完成检查、测试、打包和上线今天的内容都能直接参考。先说一个结论Python的CI/CD和Java、Go那套编译完拿产物的路线本质上不一样很多照搬过来的流水线设计放到Python项目上反而会埋雷。1. 先把话说透为什么Python做CI/CD特别容易翻车1.1 没有编译期这个天然的质检关卡Java编译有javacGo有go build类型不对、包引错了在编译阶段就报错。而Python是解释型语言语法错误甚至很多导入错误都要跑到运行时才暴露。我见过不少项目CI里只跑import xx echo ok这种假检查结果一个未定义的变量名直到线上请求打进来才现形。这意味着Python项目的CI必须自己承担更多质检职责静态检查、依赖完整性校验、单元测试、实际环境启动验证缺一个环节风险就往生产环境推。1.2 依赖管理一直是重灾区这是Python生态的老大难问题。很多项目的requirements.txt还是早期手工维护的里面写的是requests2.0这种宽松版本。今天CI装的是2.31.0一个月后变成了2.32.0小版本升级带来的行为变化可能让一个接口悄悄变慢也可能让一个兼容性写法直接报错。另外pip默认装包时会把没有声明的传递依赖按需升级这在长期运行的CI环境里简直就是定时炸弹。我在另一个项目上遇到过一次明明没人改过requirementsCI却突然红了一查是一个子依赖发了新版本破坏了兼容。1.3 环境漂移本地能跑CI不一定能跑Python开发者的本地环境往往很脏——系统Python里装了好几年的包、多个虚拟环境混着用、Windows/macOS/Linux行为还不一致。我接手过不少项目开发者说我本地跑通了拉到CI里要么缺包要么版本冲突一排查发现他本地依赖的是多年前一个被pip悄悄换掉版本的库。CI的价值之一就是用一套干净、确定性的环境来复现你的代码——但前提是流水线本身要设计得够严谨否则它复现的只是另一套脏环境。1.4 什么样的Python项目才值得上CI/CD不是所有Python脚本都要上流水线我简单分个类一次性脚本比如临时数据清洗脚本不需要CI跑完就完事。长期维护的脚本/工具比如每天自动拉数据的爬虫、内部运维工具建议至少做自动lint 自动测试部署可以手动触发。Web服务/API项目Django、Flask、FastAPI完整CI/CD全套从测试到构建镜像到自动部署。发布到PyPI的库/包CI里一定要跑多版本Python矩阵测试还要有自动打tag、自动发布到PyPI的流程。离线部署的桌面应用比如基于PyQt/Tkinter的工具CI侧重打包构建出对应的可执行文件。明确自己项目的类型才不会把流水线设计得过重或过轻。2. 流水线骨架先把最小可用跑通再谈花活很多教程一上来就是几十个步骤的大而全流水线复制过去要么跑不动要么排错排到怀疑人生。我的建议是先把最小闭环跑通拉代码 - 装依赖 - 跑检查 - 跑测试 - 留产物。跑通了再往上加部署、加通知、加缓存、加矩阵。2.1 一个能直接用的最小GitHub Actions流水线以GitHub仓库为例在.github/workflows/ci.yml放下面这个name: ci on: push: branches: [ main ] paths-ignore: - docs/** - *.md pull_request: jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 cache: pip - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements-dev.txt - name: Lint run: ruff check . - name: Test run: python -m pytest --disable-warnings -q这套骨架做了几件很关键的事paths-ignore让文档改动不触发流水线省CI时长。setup-python自带cache: pippip下载过的包会被缓存第二次跑能快一大截。先lint后testlint通常几秒就出结果代码风格有问题就别浪费时间去跑完整测试。pytest用-q静默模式失败时再去看具体报错日志短一些反而容易发现问题。2.2 触发策略push、PR、tag各管各的事触发器设计要和你团队的协作方式匹配我的习惯是触发场景执行动作pull_request全量检查lint 单元测试 构建验证push到main检查通过后自动部署到staging环境打tagv1.2.3格式检查通过后构建正式发布产物并部署生产或自动发布到PyPI这样PR阶段只负责这段代码质量过不过关合并到主干才触发上线流程避免每次push都重复跑部署逻辑。很多团队把PR和main触发都配成一套全流程结果合并一个README修改都要触发生产部署早晚翻车。2.3 别忘了concurrency不然PR大会你就要排队等CI多人协作时一个PR里连续push几个修复commit默认会并行跑多个相同流水线白烧CI额度还拖慢反馈速度。加一段配置可以自动取消旧任务concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true这样同一个分支的新push会自动取消正在跑的老任务只保留最新一次执行实测能把CI排队时间砍掉一半。2.4 从GitHub Actions转到其他平台的迁移成本并不高如果你用的是GitLab CI、Jenkins或自建Drone核心思路完全一样定义触发器、定义任务步骤、按需缓存。GitHub Actions的好处是语法简单、生态完善适合作为第一个落地的平台等玩明白之后你会发现任何CI平台要解决的其实都是同一个问题模型。3. 依赖锁定与缓存CI里最容易被忽视的稳定和速度3.1 requirements.txt时代真的应该过去了之前提到传统requirements.txt默认只写顶层依赖的宽松版本这会导致流水线每次装的依赖都不一样。我在前面那个翻车项目里用的就是这种。后来的解决方案很简单把直接依赖写进requirements.in再用pip-tools生成一份requirements.txt锁文件里面是完整依赖树每个包精确到版本号pip install pip-tools pip-compile --output-file requirements.txt requirements.in生成的requirements.txt长这样fastapi0.115.0 pydantic2.10.4 uvicorn[standard]0.34.0以后每次修改直接依赖重新跑一次pip-compile即可。所有部署环境都安装一模一样的东西从根上解决本地好的、线上挂了的问题。如果你是新项目我更推荐直接用基于pyproject.toml的工具链比如Poetry或uv。它们会自动生成锁文件poetry.lock / uv.lock安装时严格按锁文件来从机制上避免没锁依赖这件事。提示pip freeze虽然能导出当前环境的全部包版本但它会把你本地所有无关的包也一起锁进去不适合作为项目的依赖声明只适合给整个环境做精确快照。3.2 依赖安装缓存让pip install从30秒缩到5秒CI里最耗时的一步几乎总是pip install尤其是项目依赖多了以后每次全量下载非常浪费。用上缓存后的效果立竿见影使用setup-python时直接配置cache: pipGitHub官方维护缓存无需额外配置。使用其他平台时手动指定pip的缓存目录。Linux下pip缓存默认在~/.cache/pipJenkins或GitLab Runner里把它挂到持久化目录就行。我甚至会把缓存key设计成锁文件hash级别锁文件没变就直接命中缓存锁文件变了就重新下载整套依赖。这样既不会装旧包又大幅度减少网络请求。3.3 缓存需要注意的边界缓存不是越多越好。如果缓存命中策略太宽松容易遇到测试跑的是旧依赖的情况。我设过一种场景为了追求缓存命中率把key设置了requirements.txt的哈希但代码里改了新的import缓存里的旧包没有对应依赖流水线直接报错。所以缓存key一定要和依赖声明强关联依赖变了缓存就要跟着失效。3.4 再提一嘴uv现在的pip替代方案确实快很多我之前一直用pip直到试了一次uv安装依赖的速度差异非常明显。uv是用Rust重新实现包管理器的工具定位上可以同时替代pip、pip-tools和venv。在CI里可以这样用pip install uv uv pip install --system -r requirements.txt它的解析和下载速度比pip快几个量级对于依赖上百个的中大型项目节省的时间相当可观。如果团队刚起步不想折腾pip-toolsvenv那一套可以直接上uv门槛反而更低。注意如果你的项目还要兼容非常老的Python版本或依赖特殊编译选项先在自己的主力环境里跑一遍uv安装测试确认没有兼容问题再全面切换别在CI里直接开盲盒。4. 测试阶段编排lint、pytest、覆盖率与多版本矩阵4.1 lint与format现在可以只用一套工具早几年Python项目的标准配置是flake8检查 black格式化 isort排序导入三个工具各有各的配置文件偶尔还会互相打架。我现在推荐直接在CI里用ruff一个用Rust写的Python检查工具可以说快得夸张还能同时完成lint、format、import排序的检查。用起来很简单pip install ruff ruff check . ruff format --check .在CI里我通常只跑ruff check静态问题检查和ruff format --check格式校验但不去改文件让开发者本地用ruff format自动格式化CI只负责守住提交上来的代码必须是格式化过的这条红线。这一套配置下来pull request review里几乎看不到这里该加个空格这种无效评论了。4.2 pytest的正确打开方式单测是整个流水线的核心保险但很多项目的pytest配置也有一堆问题。我的CI标准写法python -m pytest --disable-warnings -q --maxfail3--disable-warnings警告信息只在真正报错时显示避免日志被刷屏。--maxfail3超过3个用例失败就终止省时间。别设成1偶尔有个脏数据导致一连串失败反而把真正的问题掩盖了。命令前面加python -m确保用的是当前虚拟环境里的解释器避免误调到系统Python。更重要的一点测试必须能在干净环境里跑起来。我经常看到开发者的测试依赖他本地某个没有写进依赖声明的包CI一跑就红。解决方法是让CI用全新的虚拟环境安装所有声明的依赖不做任何环境复用。这一下就能暴露依赖声明不全的问题。4.3 覆盖率门槛要设但别拍脑袋覆盖率这个东西我见过两种极端一种完全不设形同虚设一种上来就要求100%结果团队成员每天为了凑覆盖率写一堆没有意义的断言。我的建议是新项目从70%80%起步维护中的老项目直接设当前覆盖率再降5%作为门槛防止越做越低即可。重要的是让覆盖率报告能显示本次改动影响到的代码有没有被测试覆盖而不是单纯追求数字。用pytest-cov可以这样python -m pytest --covmy_package --cov-reportterm-missing --cov-fail-under804.4 多版本Python矩阵测试需要但分情况给第三方库做测试必须跑多版本矩阵因为使用者装了3.9就往3.9跑装了3.12就往3.12跑你没法要求他们升级。给公司内部Web服务做测试情况就完全不同——生产环境跑哪个Python版本CI重点测哪个版本就好最多再带上一个将要升级的目标版本。矩阵配置长这样在GitHub Actions里配合strategy使用strategy: matrix: python-version: [3.9, 3.10, 3.11, 3.12] steps: - uses: actions/setup-pythonv5 with: python-version: ${{ matrix.python-version }}但我不建议所有项目都上来就开四版矩阵。每多一个版本CI时间就多一份排错范围也多一层。我见过一个内部服务跑了4个版本矩阵其中3个版本根本不会出现在生产环境纯属浪费。内部服务保持主版本最低兼容版本两个组合就足够。5. 构建这一步wheel、镜像与到底要不要构建5.1 三种Python项目各自的构建形态Java、Go有明确的编译产物Python项目则要分情况纯源码部署型Django/FastAPI直接拉代码跑本质上不需要传统构建。CI里把依赖锁好、测试跑完打一个带有commit号标识的包供部署时原样拉取。库/工具型发布到PyPI或在团队内分发需要执行python -m build生成wheel包这是标准构建。容器化部署型Kubernetes、Docker Compose需要构建Docker镜像这一步通常也是真正的构建产物。5.2 发布库时的构建与发布流程如果你要发布的是一个给其他人安装的Python库关键一步是构建wheel。推荐标准做法pip install build python -m build生成dist/目录下的.whl和.tar.gz文件然后上传到PyPI。自动化发布可以在你打tag时触发一个专门的workflow用twine配合PyPI的token上传pip install twine twine upload dist/*我踩过的坑发布前没检查README里的图片链接是否迁移到了新地址结果上传成功但包描述页一堆裂图。后来我会在发布job里用一个轻量检查比如curl确认README引用的外部链接存活不然一次坏发布还好发现一个坏页面挂几个月挺尴尬的。5.3 容器镜像构建的几个硬经验很多Python服务现在都容器化部署了关于镜像构建我有几条很硬的经验尽量不用python:alpine镜像。虽然它体积小但Alpine用的是musl libc很多Python二进制包比如某些科学计算库只有manylinux的glibc版本在Alpine里没法直接用容易在pip install阶段挂掉。为了省几十兆体积去冒这个风险不值。用multi-stage build控制体积和安全性。一个典型的两段式构建FROM python:3.12-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --user -r requirements.txt FROM python:3.12-slim WORKDIR /app COPY --frombuilder /root/.local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages COPY --frombuilder /root/.local/bin/* /usr/local/bin/ COPY app/ /app/app/ CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8080]这样最终镜像只包含运行所需的依赖和代码不携带构建期的缓存和临时文件体积能小三分之一起步。如果你的镜像仓库存储空间紧张或者拉取环境网络一般这个优化很值。每个构建都打上唯一tag。我要求CI里镜像tag必须带commit短哈希比如app:7f3a9d2从不在部署流水线里用latest。理由很简单你需要能精确回滚到某一个具体代码版本而latest只是个会漂移的指针。6. 上线与回滚部署策略的细节往往决定夜里能不能睡好觉6.1 部署目标不一样流水线的最后一段完全不同把代码部署到VPS、部署到Docker Compose、部署到Kubernetes或者部署到云函数落地的配置差异很大VPS/裸机CI里用ssh远程执行git pull 重启服务看似简单但网络中断、路径不一致、启动失败都只能靠日志排查。我会在流水线里加两个保护步骤先跑迁移再跑健康检查。Docker ComposeCI直接把构建好的镜像推送到镜像仓库再远程执行docker compose pull docker compose up -d回滚就是启动上一个tag。Kubernetes通常用helm或kubectl apply新版本镜像利用滚动更新机制。CI里需要配置好kubeconfig的权限别把生产集群的master凭证写成明文挂在流水线里。Serverless/云函数上传代码包或镜像到云平台就行几乎不需要关心底层机器但也意味着无法ssh进去看日志只能靠平台日志服务排查问题。6.2 健康检查这一步必须在部署后自动执行很多部署流程在服务启动后就当成上线成功这是不对的。服务进程活着不代表服务真的能提供预期功能。我习惯在部署后自动请求一个固定的/healthz接口连续重试N次都成功才标记部署成功- name: Health check run: | for i in $(seq 1 12); do STATUS$(curl -s -o /dev/null -w %{http_code} http://service:8080/healthz) if [ $STATUS 200 ]; then exit 0; fi sleep 5 done exit 1这个检查对服务起来了但API全错这类假上线非常有效。有一次我们的服务进程正常启动但配置没读到接口全返回500健康检查直接拦住了部署流程省去了大量后续排查时间。6.3 数据迁移和代码部署的顺序最容易出事我见过不止一次事故新代码先上线旧数据库结构还没迁移请求打进来直接报字段不存在。反过来也一样先跑了迁移新代码还没上线某些旧代码引用了被删掉的字段一样崩。正确的顺序是备份数据库或至少确认备份任务最近跑过。执行迁移alembic upgrade head让数据库结构与新代码兼容。部署新代码。健康检查通过后再把旧实例切走。如果用的是容器化部署迁移不要在容器启动时自动执行。多个实例同时启动每个都跑一遍迁移轻则重复执行报错重则迁移中间状态互相干扰。把迁移放在pipeline的deploy job里单独执行只做一次。6.4 密钥管理别再往仓库里放.env了这是老生常谈但我几乎每年都会遇到有人把生产环境的数据库密码提交到Git仓库。CI系统本身都提供密钥管理功能GitHub叫SecretsGitLab叫VariablesJenkins有Credentials用法都是把敏感值存在平台的加密存储里流水线运行时通过环境变量注入这样代码库和日志里都看不到明文。我还会在流水线里加一条扫描步骤比如利用gitleaks检查明文密钥防止某天有人手滑。相比于出了事再去撤密钥、改数据库密码这条扫描的成本低得多。7. 实战踩坑清单我建议你写进团队checklist的几件事最后把我在真实项目中踩过、或在别人那里看到过的坑列成清单每一条都对应一个具体的流水线设计决策依赖相关没用锁文件某天依赖悄悄升级测试通过但线上出了兼容性问题。解决用pip-tools或uv生成锁文件严格按锁文件安装。缓存key设置太宽松CI命中旧依赖缓存测试跑到一半报缺包浪费10分钟。解决缓存key和锁文件哈希强关联。requirements-dev和requirements分离不清把开发依赖pytest、ruff混进了生产依赖导致线上镜像多装一堆无用包。解决dev依赖单独一个文件基于生产依赖叠加。测试相关pytest收集到非测试文件某个目录下放了名字带test的普通脚本被pytest当成测试跑报一堆无关错误。解决在pyproject.toml或pytest.ini里明确testpaths。maxfail设成1一个用例失败就终止排错时看不到完整失败列表。设置成35更合理。不设置覆盖率门槛覆盖率形同虚设越做越低。解决设一个合理的下限并让报告展示缺失行。构建部署相关镜像tag全用latest回滚根本不知道该回到哪一版。解决镜像tag带commit short SHA。迁移在容器启动时执行多实例并发跑迁移互相干扰。解决迁移放在部署job里执行一次。部署后不检查健康进程活着但服务不可用还以为上线成功了。解决部署后自动请求healthz接口。平台与流程相关PR和主干共用一套触发器小改动也触发完整部署链路。解决分事件配置PR只质检主干才部署。连接池、超时参数写死部署到不同环境后行为不一致。解决配置项走环境变量流水线按环境注入。.env文件进仓库数据库密码等敏感信息裸奔。解决用CI平台的Secrets功能注入环境变量。网络与安装相关pip install超时CI网络环境特殊或依赖体积大时下载经常超时。解决合理调整pip的超时参数或选择就近的依赖库镜像。使用系统Python而不是干净的虚拟环境本地没问题一上CI就缺包。解决CI中始终用虚拟环境隔离系统包。任务超时相关大项目Cron任务跑太久长时间没有完成日志难排查。解决CI平台配置job超时时间比如10分钟或30分钟超过就超时失败同时保留关键日志。这样既省资源又能尽早暴露问题。我在实际使用中最深的感受是CI/CD流水线不是一个配好就一劳永逸的东西。依赖会升级代码结构会变团队协作习惯也会变它需要像代码一样被持续维护。我自己的习惯是每个季度专门安排半天把流水线日志翻一遍看看哪些步骤在稳定浪费时长哪些步骤从来没有失败过然后果断删掉或重排。流水线是团队的时间税让它保持精简高效就是对每个人负责。最后分享一个小技巧如果你刚开始迁移到CI/CD别一口气把所有环节都自动化。先从自动跑测试开始稳定一个月再加自动lint再加自动部署到staging最后再打通生产部署。每加一个环节都留出观察期出了问题能明确知道是哪个环节引入的。这套渐进式改造我用了很多次比一次性堆一个大流水线的成功率要高得多。 
长河君 · 2026/10/7 17:08:42 · 阅读 1.2k Python项目CI/CD流水线实战：依赖锁定到自动化部署
我以前带过一个Python项目组第一版CI流水线看着挺像样——lint、单测、覆盖率、打包、部署全齐了代码一推就自动跑。结果真正上线那晚直接翻车测试环境里跑得好好的接口一到生产就报依赖版本错误排查到凌晨两点才发现流水线压根没做依赖锁定每次pip install都在装当前最新版本地、CI、生产三个环境各装各的。后来我花了两个星期把CI/CD for Python这套东西全部重做了一遍才彻底治好了这个顽疾。这篇文章就是我当时重做流水线的完整记录适合正在从手动本地跑一下再部署往自动化流水线升级的Python开发者。无论你是写Django/Flask/FastAPI的Web应用还是做爬虫脚本、数据处理工具、被分发给其他人安装的第三方库只要你希望改完代码机器自动帮我完成检查、测试、打包和上线今天的内容都能直接参考。先说一个结论Python的CI/CD和Java、Go那套编译完拿产物的路线本质上不一样很多照搬过来的流水线设计放到Python项目上反而会埋雷。1. 先把话说透为什么Python做CI/CD特别容易翻车1.1 没有编译期这个天然的质检关卡Java编译有javacGo有go build类型不对、包引错了在编译阶段就报错。而Python是解释型语言语法错误甚至很多导入错误都要跑到运行时才暴露。我见过不少项目CI里只跑import xx echo ok这种假检查结果一个未定义的变量名直到线上请求打进来才现形。这意味着Python项目的CI必须自己承担更多质检职责静态检查、依赖完整性校验、单元测试、实际环境启动验证缺一个环节风险就往生产环境推。1.2 依赖管理一直是重灾区这是Python生态的老大难问题。很多项目的requirements.txt还是早期手工维护的里面写的是requests2.0这种宽松版本。今天CI装的是2.31.0一个月后变成了2.32.0小版本升级带来的行为变化可能让一个接口悄悄变慢也可能让一个兼容性写法直接报错。另外pip默认装包时会把没有声明的传递依赖按需升级这在长期运行的CI环境里简直就是定时炸弹。我在另一个项目上遇到过一次明明没人改过requirementsCI却突然红了一查是一个子依赖发了新版本破坏了兼容。1.3 环境漂移本地能跑CI不一定能跑Python开发者的本地环境往往很脏——系统Python里装了好几年的包、多个虚拟环境混着用、Windows/macOS/Linux行为还不一致。我接手过不少项目开发者说我本地跑通了拉到CI里要么缺包要么版本冲突一排查发现他本地依赖的是多年前一个被pip悄悄换掉版本的库。CI的价值之一就是用一套干净、确定性的环境来复现你的代码——但前提是流水线本身要设计得够严谨否则它复现的只是另一套脏环境。1.4 什么样的Python项目才值得上CI/CD不是所有Python脚本都要上流水线我简单分个类一次性脚本比如临时数据清洗脚本不需要CI跑完就完事。长期维护的脚本/工具比如每天自动拉数据的爬虫、内部运维工具建议至少做自动lint 自动测试部署可以手动触发。Web服务/API项目Django、Flask、FastAPI完整CI/CD全套从测试到构建镜像到自动部署。发布到PyPI的库/包CI里一定要跑多版本Python矩阵测试还要有自动打tag、自动发布到PyPI的流程。离线部署的桌面应用比如基于PyQt/Tkinter的工具CI侧重打包构建出对应的可执行文件。明确自己项目的类型才不会把流水线设计得过重或过轻。2. 流水线骨架先把最小可用跑通再谈花活很多教程一上来就是几十个步骤的大而全流水线复制过去要么跑不动要么排错排到怀疑人生。我的建议是先把最小闭环跑通拉代码 - 装依赖 - 跑检查 - 跑测试 - 留产物。跑通了再往上加部署、加通知、加缓存、加矩阵。2.1 一个能直接用的最小GitHub Actions流水线以GitHub仓库为例在.github/workflows/ci.yml放下面这个name: ci on: push: branches: [ main ] paths-ignore: - docs/** - *.md pull_request: jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 cache: pip - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements-dev.txt - name: Lint run: ruff check . - name: Test run: python -m pytest --disable-warnings -q这套骨架做了几件很关键的事paths-ignore让文档改动不触发流水线省CI时长。setup-python自带cache: pippip下载过的包会被缓存第二次跑能快一大截。先lint后testlint通常几秒就出结果代码风格有问题就别浪费时间去跑完整测试。pytest用-q静默模式失败时再去看具体报错日志短一些反而容易发现问题。2.2 触发策略push、PR、tag各管各的事触发器设计要和你团队的协作方式匹配我的习惯是触发场景执行动作pull_request全量检查lint 单元测试 构建验证push到main检查通过后自动部署到staging环境打tagv1.2.3格式检查通过后构建正式发布产物并部署生产或自动发布到PyPI这样PR阶段只负责这段代码质量过不过关合并到主干才触发上线流程避免每次push都重复跑部署逻辑。很多团队把PR和main触发都配成一套全流程结果合并一个README修改都要触发生产部署早晚翻车。2.3 别忘了concurrency不然PR大会你就要排队等CI多人协作时一个PR里连续push几个修复commit默认会并行跑多个相同流水线白烧CI额度还拖慢反馈速度。加一段配置可以自动取消旧任务concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true这样同一个分支的新push会自动取消正在跑的老任务只保留最新一次执行实测能把CI排队时间砍掉一半。2.4 从GitHub Actions转到其他平台的迁移成本并不高如果你用的是GitLab CI、Jenkins或自建Drone核心思路完全一样定义触发器、定义任务步骤、按需缓存。GitHub Actions的好处是语法简单、生态完善适合作为第一个落地的平台等玩明白之后你会发现任何CI平台要解决的其实都是同一个问题模型。3. 依赖锁定与缓存CI里最容易被忽视的稳定和速度3.1 requirements.txt时代真的应该过去了之前提到传统requirements.txt默认只写顶层依赖的宽松版本这会导致流水线每次装的依赖都不一样。我在前面那个翻车项目里用的就是这种。后来的解决方案很简单把直接依赖写进requirements.in再用pip-tools生成一份requirements.txt锁文件里面是完整依赖树每个包精确到版本号pip install pip-tools pip-compile --output-file requirements.txt requirements.in生成的requirements.txt长这样fastapi0.115.0 pydantic2.10.4 uvicorn[standard]0.34.0以后每次修改直接依赖重新跑一次pip-compile即可。所有部署环境都安装一模一样的东西从根上解决本地好的、线上挂了的问题。如果你是新项目我更推荐直接用基于pyproject.toml的工具链比如Poetry或uv。它们会自动生成锁文件poetry.lock / uv.lock安装时严格按锁文件来从机制上避免没锁依赖这件事。提示pip freeze虽然能导出当前环境的全部包版本但它会把你本地所有无关的包也一起锁进去不适合作为项目的依赖声明只适合给整个环境做精确快照。3.2 依赖安装缓存让pip install从30秒缩到5秒CI里最耗时的一步几乎总是pip install尤其是项目依赖多了以后每次全量下载非常浪费。用上缓存后的效果立竿见影使用setup-python时直接配置cache: pipGitHub官方维护缓存无需额外配置。使用其他平台时手动指定pip的缓存目录。Linux下pip缓存默认在~/.cache/pipJenkins或GitLab Runner里把它挂到持久化目录就行。我甚至会把缓存key设计成锁文件hash级别锁文件没变就直接命中缓存锁文件变了就重新下载整套依赖。这样既不会装旧包又大幅度减少网络请求。3.3 缓存需要注意的边界缓存不是越多越好。如果缓存命中策略太宽松容易遇到测试跑的是旧依赖的情况。我设过一种场景为了追求缓存命中率把key设置了requirements.txt的哈希但代码里改了新的import缓存里的旧包没有对应依赖流水线直接报错。所以缓存key一定要和依赖声明强关联依赖变了缓存就要跟着失效。3.4 再提一嘴uv现在的pip替代方案确实快很多我之前一直用pip直到试了一次uv安装依赖的速度差异非常明显。uv是用Rust重新实现包管理器的工具定位上可以同时替代pip、pip-tools和venv。在CI里可以这样用pip install uv uv pip install --system -r requirements.txt它的解析和下载速度比pip快几个量级对于依赖上百个的中大型项目节省的时间相当可观。如果团队刚起步不想折腾pip-toolsvenv那一套可以直接上uv门槛反而更低。注意如果你的项目还要兼容非常老的Python版本或依赖特殊编译选项先在自己的主力环境里跑一遍uv安装测试确认没有兼容问题再全面切换别在CI里直接开盲盒。4. 测试阶段编排lint、pytest、覆盖率与多版本矩阵4.1 lint与format现在可以只用一套工具早几年Python项目的标准配置是flake8检查 black格式化 isort排序导入三个工具各有各的配置文件偶尔还会互相打架。我现在推荐直接在CI里用ruff一个用Rust写的Python检查工具可以说快得夸张还能同时完成lint、format、import排序的检查。用起来很简单pip install ruff ruff check . ruff format --check .在CI里我通常只跑ruff check静态问题检查和ruff format --check格式校验但不去改文件让开发者本地用ruff format自动格式化CI只负责守住提交上来的代码必须是格式化过的这条红线。这一套配置下来pull request review里几乎看不到这里该加个空格这种无效评论了。4.2 pytest的正确打开方式单测是整个流水线的核心保险但很多项目的pytest配置也有一堆问题。我的CI标准写法python -m pytest --disable-warnings -q --maxfail3--disable-warnings警告信息只在真正报错时显示避免日志被刷屏。--maxfail3超过3个用例失败就终止省时间。别设成1偶尔有个脏数据导致一连串失败反而把真正的问题掩盖了。命令前面加python -m确保用的是当前虚拟环境里的解释器避免误调到系统Python。更重要的一点测试必须能在干净环境里跑起来。我经常看到开发者的测试依赖他本地某个没有写进依赖声明的包CI一跑就红。解决方法是让CI用全新的虚拟环境安装所有声明的依赖不做任何环境复用。这一下就能暴露依赖声明不全的问题。4.3 覆盖率门槛要设但别拍脑袋覆盖率这个东西我见过两种极端一种完全不设形同虚设一种上来就要求100%结果团队成员每天为了凑覆盖率写一堆没有意义的断言。我的建议是新项目从70%80%起步维护中的老项目直接设当前覆盖率再降5%作为门槛防止越做越低即可。重要的是让覆盖率报告能显示本次改动影响到的代码有没有被测试覆盖而不是单纯追求数字。用pytest-cov可以这样python -m pytest --covmy_package --cov-reportterm-missing --cov-fail-under804.4 多版本Python矩阵测试需要但分情况给第三方库做测试必须跑多版本矩阵因为使用者装了3.9就往3.9跑装了3.12就往3.12跑你没法要求他们升级。给公司内部Web服务做测试情况就完全不同——生产环境跑哪个Python版本CI重点测哪个版本就好最多再带上一个将要升级的目标版本。矩阵配置长这样在GitHub Actions里配合strategy使用strategy: matrix: python-version: [3.9, 3.10, 3.11, 3.12] steps: - uses: actions/setup-pythonv5 with: python-version: ${{ matrix.python-version }}但我不建议所有项目都上来就开四版矩阵。每多一个版本CI时间就多一份排错范围也多一层。我见过一个内部服务跑了4个版本矩阵其中3个版本根本不会出现在生产环境纯属浪费。内部服务保持主版本最低兼容版本两个组合就足够。5. 构建这一步wheel、镜像与到底要不要构建5.1 三种Python项目各自的构建形态Java、Go有明确的编译产物Python项目则要分情况纯源码部署型Django/FastAPI直接拉代码跑本质上不需要传统构建。CI里把依赖锁好、测试跑完打一个带有commit号标识的包供部署时原样拉取。库/工具型发布到PyPI或在团队内分发需要执行python -m build生成wheel包这是标准构建。容器化部署型Kubernetes、Docker Compose需要构建Docker镜像这一步通常也是真正的构建产物。5.2 发布库时的构建与发布流程如果你要发布的是一个给其他人安装的Python库关键一步是构建wheel。推荐标准做法pip install build python -m build生成dist/目录下的.whl和.tar.gz文件然后上传到PyPI。自动化发布可以在你打tag时触发一个专门的workflow用twine配合PyPI的token上传pip install twine twine upload dist/*我踩过的坑发布前没检查README里的图片链接是否迁移到了新地址结果上传成功但包描述页一堆裂图。后来我会在发布job里用一个轻量检查比如curl确认README引用的外部链接存活不然一次坏发布还好发现一个坏页面挂几个月挺尴尬的。5.3 容器镜像构建的几个硬经验很多Python服务现在都容器化部署了关于镜像构建我有几条很硬的经验尽量不用python:alpine镜像。虽然它体积小但Alpine用的是musl libc很多Python二进制包比如某些科学计算库只有manylinux的glibc版本在Alpine里没法直接用容易在pip install阶段挂掉。为了省几十兆体积去冒这个风险不值。用multi-stage build控制体积和安全性。一个典型的两段式构建FROM python:3.12-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --user -r requirements.txt FROM python:3.12-slim WORKDIR /app COPY --frombuilder /root/.local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages COPY --frombuilder /root/.local/bin/* /usr/local/bin/ COPY app/ /app/app/ CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8080]这样最终镜像只包含运行所需的依赖和代码不携带构建期的缓存和临时文件体积能小三分之一起步。如果你的镜像仓库存储空间紧张或者拉取环境网络一般这个优化很值。每个构建都打上唯一tag。我要求CI里镜像tag必须带commit短哈希比如app:7f3a9d2从不在部署流水线里用latest。理由很简单你需要能精确回滚到某一个具体代码版本而latest只是个会漂移的指针。6. 上线与回滚部署策略的细节往往决定夜里能不能睡好觉6.1 部署目标不一样流水线的最后一段完全不同把代码部署到VPS、部署到Docker Compose、部署到Kubernetes或者部署到云函数落地的配置差异很大VPS/裸机CI里用ssh远程执行git pull 重启服务看似简单但网络中断、路径不一致、启动失败都只能靠日志排查。我会在流水线里加两个保护步骤先跑迁移再跑健康检查。Docker ComposeCI直接把构建好的镜像推送到镜像仓库再远程执行docker compose pull docker compose up -d回滚就是启动上一个tag。Kubernetes通常用helm或kubectl apply新版本镜像利用滚动更新机制。CI里需要配置好kubeconfig的权限别把生产集群的master凭证写成明文挂在流水线里。Serverless/云函数上传代码包或镜像到云平台就行几乎不需要关心底层机器但也意味着无法ssh进去看日志只能靠平台日志服务排查问题。6.2 健康检查这一步必须在部署后自动执行很多部署流程在服务启动后就当成上线成功这是不对的。服务进程活着不代表服务真的能提供预期功能。我习惯在部署后自动请求一个固定的/healthz接口连续重试N次都成功才标记部署成功- name: Health check run: | for i in $(seq 1 12); do STATUS$(curl -s -o /dev/null -w %{http_code} http://service:8080/healthz) if [ $STATUS 200 ]; then exit 0; fi sleep 5 done exit 1这个检查对服务起来了但API全错这类假上线非常有效。有一次我们的服务进程正常启动但配置没读到接口全返回500健康检查直接拦住了部署流程省去了大量后续排查时间。6.3 数据迁移和代码部署的顺序最容易出事我见过不止一次事故新代码先上线旧数据库结构还没迁移请求打进来直接报字段不存在。反过来也一样先跑了迁移新代码还没上线某些旧代码引用了被删掉的字段一样崩。正确的顺序是备份数据库或至少确认备份任务最近跑过。执行迁移alembic upgrade head让数据库结构与新代码兼容。部署新代码。健康检查通过后再把旧实例切走。如果用的是容器化部署迁移不要在容器启动时自动执行。多个实例同时启动每个都跑一遍迁移轻则重复执行报错重则迁移中间状态互相干扰。把迁移放在pipeline的deploy job里单独执行只做一次。6.4 密钥管理别再往仓库里放.env了这是老生常谈但我几乎每年都会遇到有人把生产环境的数据库密码提交到Git仓库。CI系统本身都提供密钥管理功能GitHub叫SecretsGitLab叫VariablesJenkins有Credentials用法都是把敏感值存在平台的加密存储里流水线运行时通过环境变量注入这样代码库和日志里都看不到明文。我还会在流水线里加一条扫描步骤比如利用gitleaks检查明文密钥防止某天有人手滑。相比于出了事再去撤密钥、改数据库密码这条扫描的成本低得多。7. 实战踩坑清单我建议你写进团队checklist的几件事最后把我在真实项目中踩过、或在别人那里看到过的坑列成清单每一条都对应一个具体的流水线设计决策依赖相关没用锁文件某天依赖悄悄升级测试通过但线上出了兼容性问题。解决用pip-tools或uv生成锁文件严格按锁文件安装。缓存key设置太宽松CI命中旧依赖缓存测试跑到一半报缺包浪费10分钟。解决缓存key和锁文件哈希强关联。requirements-dev和requirements分离不清把开发依赖pytest、ruff混进了生产依赖导致线上镜像多装一堆无用包。解决dev依赖单独一个文件基于生产依赖叠加。测试相关pytest收集到非测试文件某个目录下放了名字带test的普通脚本被pytest当成测试跑报一堆无关错误。解决在pyproject.toml或pytest.ini里明确testpaths。maxfail设成1一个用例失败就终止排错时看不到完整失败列表。设置成35更合理。不设置覆盖率门槛覆盖率形同虚设越做越低。解决设一个合理的下限并让报告展示缺失行。构建部署相关镜像tag全用latest回滚根本不知道该回到哪一版。解决镜像tag带commit short SHA。迁移在容器启动时执行多实例并发跑迁移互相干扰。解决迁移放在部署job里执行一次。部署后不检查健康进程活着但服务不可用还以为上线成功了。解决部署后自动请求healthz接口。平台与流程相关PR和主干共用一套触发器小改动也触发完整部署链路。解决分事件配置PR只质检主干才部署。连接池、超时参数写死部署到不同环境后行为不一致。解决配置项走环境变量流水线按环境注入。.env文件进仓库数据库密码等敏感信息裸奔。解决用CI平台的Secrets功能注入环境变量。网络与安装相关pip install超时CI网络环境特殊或依赖体积大时下载经常超时。解决合理调整pip的超时参数或选择就近的依赖库镜像。使用系统Python而不是干净的虚拟环境本地没问题一上CI就缺包。解决CI中始终用虚拟环境隔离系统包。任务超时相关大项目Cron任务跑太久长时间没有完成日志难排查。解决CI平台配置job超时时间比如10分钟或30分钟超过就超时失败同时保留关键日志。这样既省资源又能尽早暴露问题。我在实际使用中最深的感受是CI/CD流水线不是一个配好就一劳永逸的东西。依赖会升级代码结构会变团队协作习惯也会变它需要像代码一样被持续维护。我自己的习惯是每个季度专门安排半天把流水线日志翻一遍看看哪些步骤在稳定浪费时长哪些步骤从来没有失败过然后果断删掉或重排。流水线是团队的时间税让它保持精简高效就是对每个人负责。最后分享一个小技巧如果你刚开始迁移到CI/CD别一口气把所有环节都自动化。先从自动跑测试开始稳定一个月再加自动lint再加自动部署到staging最后再打通生产部署。每加一个环节都留出观察期出了问题能明确知道是哪个环节引入的。这套渐进式改造我用了很多次比一次性堆一个大流水线的成功率要高得多。