通过GitHub Actions与Python CDK部署至AWS时遇ModuleNotFoundError

仓库结构 #

.
├── .github
│   └── workflows/
├── .gitignore
├── README.md
├── backend/
├── cdk
│   ├── .env
│   ├── .gitignore
│   ├── README.md
│   ├── __pycache__
│   ├── app.py
│   ├── cdk.context.json
│   ├── cdk.json
│   ├── cdk.out
│   ├── poetry.lock
│   ├── pyproject.toml
│   ├── schema.json
│   ├── settings.py
│   ├── stacks
│   └── tests
└── frontend/

cdk目录存放Python编写的AWS CDK代码，使用Poetry管理依赖。

当前GitHub Actions工作流配置 #

触发分支为dev，部署作业配置如下：

jobs:
  aws_cdk:

    permissions:
      contents: 'read'
      id-token: 'write'

    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Configure AWS credentials
        if: github.ref == 'refs/heads/dev'
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Run `cdk deploy`
        if: github.ref == 'refs/heads/dev'
        uses: youyo/aws-cdk-github-actions@v2
        env:
          AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID}}
        with:
          cdk_subcommand: 'deploy'
          cdk_stack: 'StreamingStack'
          cdk_version: 'latest'
          cdk_args: '--require-approval never'
          actions_comment: false
          working_dir: './cdk'

报错信息 #

部署时触发ModuleNotFoundError：

added 1 package in 856ms
Install aws-cdk latest
Successful install aws-cdk latest
Run cdk deploy --require-approval never "StreamingStack"
Traceback (most recent call last):
  File "/github/workspace/cdk/app.py", line 2, in <module>
    import aws_cdk as cdk
ModuleNotFoundError: No module named 'aws_cdk'

已尝试的修复步骤 #

在部署前添加了Poetry相关安装步骤，但问题未解决：

- name: Install desired Python version
  uses: actions/setup-python@v5
  with:
    python-version: ${{ env.PYTHON_VERSION }}

- name: Install Poetry
  uses: snok/install-poetry@v1
  with:
    version: ${{ env.POETRY_VERSION }}
    virtualenvs-create: false
    virtualenvs-in-project: false

- name: Install CDK dependencies
  run: |
    poetry config virtualenvs.create false
    poetry install --no-interaction --no-ansi --directory='./cdk'

pyproject.toml内容 #

[tool.poetry]
name = "cdk"
version = "0.1.0"
description = ""
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
aws-cdk-lib = "^2.115.0"
pydantic_settings = "^2.1.0"
"aws-amplify.cdk.exported-backend" = "^0.0.6"
constructs = ">=10.0.0,<11.0.0"


[tool.poetry.group.dev.dependencies]
pytest = "^7.4.3"

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

解决思路 #

1. 解决环境不一致问题 #

youyo/aws-cdk-github-actions会自动全局安装aws-cdk CLI，该CLI可能使用了与你通过setup-python配置的不同Python环境，导致Poetry安装的依赖无法被识别。

修复方案：跳过action的自动CDK安装，改用Poetry环境直接执行cdk命令：

# 替换原有的Run `cdk deploy`步骤
- name: Run `cdk deploy`
  if: github.ref == 'refs/heads/dev'
  working-directory: ./cdk
  run: |
    poetry run cdk deploy StreamingStack --require-approval never
  env:
    AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID}}
    AWS_REGION: ${{ env.AWS_REGION }}

2. 验证依赖安装状态 #

在安装依赖后添加调试步骤，确认依赖是否正确安装到当前环境：

- name: Verify dependencies
  working-directory: ./cdk
  run: |
    python --version
    poetry run pip list | grep -E "(aws-cdk-lib|constructs)"

3. 修正cdk.json的执行命令 #

确保cdk/cdk.json中的app命令使用Poetry环境运行Python：

{
  "app": "poetry run python app.py",
  "watch": {
    "include": [
      "**"
    ],
    "exclude": [
      "README.md",
      "cdk*.json",
      "requirements*.txt",
      "source.bat",
      "**/__pycache__",
      "**/tests"
    ]
  },
  "context": {
    ...
  }
}

4. 确保Python版本匹配 #

确认env.PYTHON_VERSION的值为3.11.x，与pyproject.toml中指定的python = "^3.11"一致，避免版本不兼容导致依赖安装失败。

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