使用Maturin的Python项目在GitHub Workflow构建失败解决方案咨询

我有一个用PyO3绑定实现Rust扩展模块的Python项目，本地和ReadTheDocs上用pip install .都能正常构建，会生成对应架构的本地wheel包。但在GitHub Workflow中构建失败，相关Workflow配置如下：

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11"]

    steps:
    - uses: actions/checkout@v4
    - name: Set up Rust
      uses: actions-rust-lang/setup-rust-toolchain@v1
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v3
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install . -v

失败核心原因是GitHub环境中Rust编译器把警告直接当成错误处理，而其他环境会忽略这些警告。示例错误如下：

error: unused import: `Axis`
    --> src/dual/dual2.rs:12:38
     |
  12 | use ndarray::{Array, Array1, Array2, Axis};
     |                                      ^^^^
     |
     = note: `-D unused-imports` implied by `-D warnings`
     = help: to override `-D warnings` add `#[allow(unused_imports)]`

即使移除部分未使用的导入，仍有一些没必要修改的警告被判定为错误，最终导致构建终止：

💥 maturin failed
    Caused by: Failed to build a native library through cargo
    Caused by: Cargo build finished with "exit status: 101": `env -u CARGO PYO3_ENVIRONMENT_SIGNATURE="cpython-3.11-64bit" PYO3_PYTHON="/opt/hostedtoolcache/Python/3.11.8/x64/bin/python" PYTHON_SYS_EXECUTABLE="/opt/hostedtoolcache/Python/3.11.8/x64/bin/python" "cargo" "rustc" "--message-format" "json-render-diagnostics" "--manifest-path" "/home/runner/work/folder/Cargo.toml" "--release" "--lib" "--crate-type" "cdylib"`
  Error: command ['maturin', 'pep517', 'build-wheel', '-i', '/opt/hostedtoolcache/Python/3.11.8/x64/bin/python', '--compatibility', 'off'] returned non-zero exit status 1
  error: subprocess-exited-with-error

如何解决这个问题，让项目能在GitHub Actions中正常构建？

方法1：调整setup-rust-toolchain的默认配置 #

actions-rust-lang/setup-rust-toolchain@v1默认会开启-D warnings（将所有警告转为错误），直接在该步骤中显式关闭此规则即可：

- name: Set up Rust
  uses: actions-rust-lang/setup-rust-toolchain@v1
  with:
    deny-warnings: false

方法2：在GitHub Actions中临时设置环境变量 #

在构建步骤前添加环境变量，让Cargo不将警告转为错误：

- name: Install dependencies
  env:
    RUSTFLAGS: "-A warnings"
  run: |
    python -m pip install --upgrade pip
    pip install . -v

如果只想忽略特定类型的警告，比如未使用导入，可以更精准地设置：

- name: Install dependencies
  env:
    RUSTFLAGS: "-A unused-imports -A unused-variables"
  run: |
    python -m pip install --upgrade pip
    pip install . -v

方法3：在Cargo.toml中配置警告等级 #

在项目的Cargo.toml里添加编译配置，自定义哪些警告需要转为错误：

[profile.release]
# 仅将指定严重警告转为错误，其余警告忽略
warn = ["unused-extern-crates", "missing-docs"]

如果需要仅在GitHub环境中生效，可以结合条件编译：

[profile.release]
warn = ["unused-extern-crates", "missing-docs"]

[target.'cfg(github_actions)'.profile.release]
warn = []

同时在Workflow中添加环境变量传递条件：

- name: Set Rust build flags
  run: echo "RUSTFLAGS=--cfg github_actions" >> $GITHUB_ENV

方法4：针对性忽略代码中的特定警告 #

如果不想全局放宽规则，可在代码中添加属性忽略特定警告，比如针对未使用的导入：

#[allow(unused_imports)]
use ndarray::{Array, Array1, Array2, Axis};

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