PyO3混合项目含Python目录时无法完整编译问题

问题根源 #

当项目包含python目录时，Maturin默认启用混合Python/Rust包构建模式。此模式下，Maturin仅编译lib.rs中被PyO3导出逻辑关联的Rust代码，未被引用的纯Rust模块会被编译器忽略，导致无法编译全部Rust代码。

解决步骤 #

1. 强制所有Rust模块被编译 #

无论纯Rust模块是否需要暴露给Python，都必须在lib.rs中通过mod声明引入，并确保它们被编译链路覆盖：

• 如果模块被PyO3导出的类/函数直接或间接使用，只需正常引入即可：

  // src/lib.rs
  mod utils; // 引入纯Rust模块
  
  use pyo3::prelude::*;
  
  #[pyclass]
  pub struct MyPyClass {
      inner: utils::InnerStruct, // 间接引用触发编译
  }
  

• 如果模块仅作为内部依赖无需暴露给Python，添加#[used]属性强制编译器保留：

  // src/lib.rs
  mod core_logic;
  
  #[used]
  static _FORCE_COMPILE: &core_logic::CoreComponent = &core_logic::CoreComponent;
  

2. 配置pyproject.toml确保完整编译 #

在pyproject.toml中明确Maturin的混合模式配置，确保它完整编译整个Rust crate：

[tool.maturin]
mixed = true
cargo-path = "./Cargo.toml" # 显式指定Cargo配置路径，避免歧义
cargo-features = ["pyo3/extension-module"]

3. 规范Python目录结构 #

python目录下的包名必须与Rust导出的模块名一致，示例结构：

python/
└── lclPy/
    ├── __init__.py
    └── python_utils.py

在__init__.py中整合Rust扩展与Python代码：

# python/lclPy/__init__.py
from .lclPy import *  # 导入Rust编译的扩展模块
from .python_utils import *

4. 验证编译命令 #

使用以下命令确保完整编译：

# 开发模式构建
maturin develop --release

# 或者先编译Rust再构建Python包
cargo build --release --lib
maturin build

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