Github Actions无法识别Poetry安装的dev依赖，CDK部署失败

本地执行poetry install后运行cdk deploy --context stage="dev"可成功部署基于Mangum的Python服务与CDK栈，但在Github Actions中执行相同流程时，出现ModuleNotFoundError: No module named 'aws_cdk'错误，无法识别Poetry安装的dev依赖（如aws-cdk-lib）。手动用pip安装所需dev依赖虽能解决，但会导致部署包过大被拒绝，这是当前CI/CD流程的核心阻碍。

相关配置文件 #

pyproject.toml #

[tool.poetry]
name = "dics-core-data-service"
version = "0.1.0"
description = ""
authors = ["Clayton <clayton.stetz@gmail.com>"]
readme = "README.md"
package-mode = false

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.115.0"
uvicorn = "^0.31.0"
python-dotenv = "^1.0.1"
pydantic = {extras = ["email"], version = "^2.9.2"}
phonenumbers = "^8.13.46"
pydantic-extra-types = "^2.9.0"
mangum = "^0.19.0"
constructs = "^10.3.0"
psycopg2-binary = "^2.9.9"

[tool.poetry.dev-dependencies]
pytest = "^8.3.3" 
aws-cdk-lib = "^2.161.1"
aws-cdk-aws-lambda-python-alpha = "^2.161.1a0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

poetry.lock 相关片段 #

[[package]]
name = "aws-cdk-lib"
version = "2.161.1"
description = "Version 2 of the AWS Cloud Development Kit library"
optional = false
python-versions = "~=3.8"
files = [
    {file = "aws_cdk_lib-2.161.1-py3-none-any.whl", hash = "sha256:c7de930396b1b9f0f512a728a1b926c77c3cab28fbc11fd4f81819dd9563bfb3"},
    {file = "aws_cdk_lib-2.161.1.tar.gz", hash = "sha256:e27a427bc6d95dd2eb0500b0de628a88ee587b212f999fa6efb7e9ab17980201"},
]

[package.dependencies]
"aws-cdk.asset-awscli-v1" = ">=2.2.202,<3.0.0"
"aws-cdk.asset-kubectl-v20" = ">=2.1.2,<3.0.0"
"aws-cdk.asset-node-proxy-agent-v6" = ">=2.1.0,<3.0.0"
"aws-cdk.cloud-assembly-schema" = ">=38.0.0,<39.0.0"
constructs = ">=10.0.0,<11.0.0"
jsii = ">=1.103.1,<2.0.0"
publication = ">=0.0.3"
typeguard = ">=2.13.3,<5.0.0"

[[package]]
name = "aws-cdk-aws-lambda-python-alpha"
version = "2.161.1a0"
description = "The CDK Construct Library for AWS Lambda in Python"
optional = false
python-versions = "~=3.8"
files = [
    {file = "aws_cdk.aws_lambda_python_alpha-2.161.1a0-py3-none-any.whl", hash = "sha256:bc50b108080d06c68d0d8468467b59751082e1a7b553452a92175bf03e38d0aa"},
    {file = "aws_cdk_aws_lambda_python_alpha-2.161.1a0.tar.gz", hash = "sha256:3543cbaeabb6fb2c8e694cf5c2525ab5f1965130cc7db79a929c8c38be40db84"},
]

[package.dependencies]
aws-cdk-lib = ">=2.161.1,<3.0.0"
constructs = ">=10.0.0,<11.0.0"
jsii = ">=1.103.1,<2.0.0"
publication = ">=0.0.3"
typeguard = ">=2.13.3,<5.0.0"

Github Actions 配置文件 #

name: AWS Service CI/CD

on:
  push:
    branches: [dev]
  
jobs:
  build:
    environment: dev
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python 3.12
        uses: actions/setup-python@v4
        with:
          python-version: "3.12"
      - name: Set up Node
        uses: actions/setup-node@v3
        with:
          node-version: "22" 
      - name: Service - Install Python and CDK
        run: |
          cd serverlessservice
          python -m pip install --upgrade pip         
          npm install -g aws-cdk
      - name: Service - Install Poetry
        uses: Gr1N/setup-poetry@v8
      - name: Service - Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@master
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: "us-west-2"
      - name: Service - Install Dependencies
        run: |
          cd serverlessservice  

          poetry install

          cdk deploy --context stage="dev"

错误信息 #

Traceback (most recent call last):
  File "/home/runner/work/core-data-service/core-data-service/serverlessservice/./infra.py", line 2, in <module>
    import aws_cdk as cdk
ModuleNotFoundError: No module named 'aws_cdk'
Subprocess exited with error 1

核心原因 #

全局安装的cdk命令默认使用系统Python环境，而Poetry将dev依赖（包括aws-cdk-lib）安装在独立的虚拟环境中，两者环境不互通，导致cdk无法找到aws_cdk模块。

解决步骤 #

调整Github Actions中的部署逻辑，让cdk deploy在Poetry的虚拟环境中执行，有两种可行方式：

方式1：用poetry run包裹cdk命令 #

修改最后一步的部署命令，通过poetry run强制使用Poetry虚拟环境的Python解释器：

- name: Service - Install Dependencies and Deploy
  run: |
    cd serverlessservice  
    poetry install
    poetry run cdk deploy --context stage="dev" --require-approval never

方式2：先激活Poetry虚拟环境再执行cdk #

先激活虚拟环境，再运行cdk命令，确保环境一致：

- name: Service - Install Dependencies and Deploy
  run: |
    cd serverlessservice  
    poetry install
    source $(poetry env info --path)/bin/activate
    cdk deploy --context stage="dev" --require-approval never

额外优化 #

• 添加--require-approval never参数，避免部署时需要手动确认，适配CI/CD自动化场景。
• 安装Poetry时指定稳定版本，避免版本差异引发问题：

- name: Service - Install Poetry
  uses: Gr1N/setup-poetry@v8
  with:
    poetry-version: "1.8.3"

内容的提问来源于stack exchange，提问作者kamii