python通过rust编写组件扩展自己的能力

PyO3 + Maturin 完整安装与使用手册

一、基础项目信息

1.1 PyO3 核心信息

表格

项目	内容
GitHub 地址	https://github.com/PyO3/pyo3
官方文档	https://pyo3.rs
开源协议	MIT / Apache-2.0 双协议，支持免费商用
稳定版本	0.23.x
Python 支持	Python 3.8+，兼容 CPython、PyPy、GraalPy
配套构建工具	maturin（官方推荐）

1.2 Maturin 核心信息

maturin 为 PyO3 配套构建工具，用于将 Rust 代码编译为 Python 可直接安装的 .whl 包

表格

项目	内容
GitHub 地址	https://github.com/PyO3/maturin
官方文档	https://www.maturin.rs
最新版本	1.12.2（2026 年 3 月发布）
开源协议	Apache-2.0 / MIT 双协议

二、前置环境安装

2.1 安装 Rust 工具链

bash

运行

复制代码

# 一键安装 rustup、rustc、cargo
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装完成后重启终端，验证安装：

bash

运行

复制代码

rustc --version
cargo --version

2.2 安装 maturin（三选一，uv 方案推荐）

bash

运行

复制代码

# 方案1：uv 安装（推荐，适配 uv 项目工作流）
uv tool install maturin

# 方案2：pipx 安装
pipx install maturin

# 方案3：原生 pip 安装
pip install maturin

验证 maturin 是否生效：

bash

运行

复制代码

maturin --version

三、完整项目开发流程

3.1 创建 PyO3 混合项目

bash

运行

复制代码

# 新建项目 my_fast_tool
maturin new my_fast_tool
cd my_fast_tool

自动生成目录结构：

plaintext

复制代码

my_fast_tool/
├── Cargo.toml          # Rust 依赖配置
├── pyproject.toml      # Python 打包规范配置
└── src/
    └── lib.rs          # Rust 核心代码（Python 导出逻辑）

3.2 编写 Rust 导出代码（src/lib.rs）

rust

运行

复制代码

use pyo3::prelude::*;

// 标记函数可暴露至 Python
#[pyfunction]
fn fast_calculate(numbers: Vec<i64>) -> i64 {
    numbers.iter().sum()
}

// 模块入口：注册所有导出函数
#[pymodule]
fn my_fast_tool(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(fast_calculate, m)?)?;
    Ok(())
}

3.3 编译项目（两种模式）

模式 1：开发调试（热加载，推荐日常迭代）

编译后自动安装至当前虚拟环境，修改代码无需手动重装

bash

运行

复制代码

maturin develop

模式 2：生产打包（生成 whl 安装包）

bash

运行

复制代码

maturin build --release

产物输出目录：target/wheels/

3.4 使用 uv 安装编译后的 whl 包

bash

运行

复制代码

# 写入项目依赖（更新 pyproject.toml）
uv add ./target/wheels/my_fast_tool-0.1.0-cp312-cp312-linux_x86_64.whl

# 仅安装至虚拟环境，不修改项目配置
uv pip install ./target/wheels/my_fast_tool-0.1.0-cp312-cp312-linux_x86_64.whl

3.5 Python 调用 Rust 代码

python

运行

复制代码

import my_fast_tool

res = my_fast_tool.fast_calculate([1, 2, 3, 4, 5])
print(res)  # 输出 15

四、发布至 PyPI（可选）

方式 1：maturin 一键发布

bash

运行

复制代码

maturin publish

方式 2：maturin 打包 + uv 发布

bash

运行

复制代码

# 先构建 release 包
maturin build --release
# 使用 uv 上传至 PyPI
uv publish

五、整体流程总结

plaintext

复制代码

安装 Rust + maturin
       ↓
maturin new 创建混合项目
       ↓
编写 src/lib.rs Rust 业务代码
       ↓
maturin develop 本地调试
    或
maturin build --release 生成 whl 包
       ↓
uv add / uv pip install 安装编译包
       ↓
Python import 直接调用 Rust 高性能函数