onnxruntime DLL 加载失败：完整排查与修复

Python 3.12 Embeddable + onnxruntime DLL 加载失败：完整排查与修复

目标读者 ：AI Agent / 自动化脚本
问题场景 ：在 Windows 上制作 Python 便携包时，onnxruntime 的 .pyd 文件无法加载
修复时间 ：2026-05-18
验证环境：Windows 11 + Python 3.12.10 embeddable-amd64

一、问题症状

python 复制代码

import onnxruntime

抛出异常：

复制代码

ImportError: DLL load failed while importing onnxruntime_pybind11_state: 拒绝访问。

关键特征：

错误码是 WinError 5（拒绝访问），不是 WinError 126（找不到模块）
文件存在、权限正确、无 Zone.Identifier 标记
其他 .pyd 文件（如 numpy、msgpack）可正常加载
仅 onnxruntime 的 onnxruntime_pybind11_state.pyd 无法加载

二、环境信息

复制代码

OS: Windows 11 64-bit
Python: 3.12.10 embeddable-amd64 (官方 zip 版)
原始安装: pip install onnxruntime  →  安装的是 1.26.0

三、排查过程（AI 可直接复现）

3.1 确认不是权限问题

bash 复制代码

# 检查文件权限
icacls "python/Lib/site-packages/onnxruntime/capi/onnxruntime_pybind11_state.pyd"
# 输出：BUILTIN\Users:(I)(RX)  →  读取执行权限正常

# 检查是否被 Windows 标记为"来自互联网"
powershell -Command "Get-Item 'python/Lib/site-packages/onnxruntime/capi/onnxruntime_pybind11_state.pyd' -Stream *"
# 输出：只有 :$DATA，无 Zone.Identifier

结论：不是权限或文件标记问题。

3.2 确认不是 VC++ 运行库缺失

bash 复制代码

# 系统已安装 VC++ 2015-2022 Redistributable (x64)
reg query "HKLM\SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64" /v Installed
# 输出：Installed REG_DWORD 0x1

# 尝试复制系统 DLL 到 python 目录
cp /c/Windows/System32/msvcp140.dll python/
cp /c/Windows/System32/vcruntime140.dll python/
cp /c/Windows/System32/vcruntime140_1.dll python/
# 结果：仍然报错

结论：不是 VC++ 运行库缺失。

3.3 尝试不同 onnxruntime 版本

bash 复制代码

# 方案 A：最新版 CPU
pip install onnxruntime==1.26.0
# 结果：❌ DLL 加载失败

# 方案 B：GPU 版
pip install onnxruntime-gpu==1.26.0
# 结果：❌ DLL 加载失败

# 方案 C：DirectML 版
pip install onnxruntime-directml==1.24.4
# 结果：❌ DLL 加载失败

# 方案 D：OpenVINO 版
pip install onnxruntime-openvino==1.24.1
# 结果：❌ DLL 加载失败

# 方案 E：降级到 1.20.1
pip install onnxruntime==1.20.1
# 结果：❌ DLL 加载失败

# 方案 F：降级到 1.19.2
pip install onnxruntime==1.19.2
# 结果：❌ DLL 加载失败

# 方案 G：降级到 1.17.0
pip install onnxruntime==1.17.0
# 结果：✅ 正常加载！

3.4 验证 Python 版本的影响

bash 复制代码

# 用 conda 创建 Python 3.10 环境测试
conda create -n test python=3.10
conda activate test
pip install onnxruntime==1.23.2
python -c "import onnxruntime; print(onnxruntime.__version__)"
# 结果：✅ 1.23.2 正常加载

关键发现：

Python 3.10 可以运行 onnxruntime 1.23.2
Python 3.12 embeddable 只能运行 onnxruntime ≤1.17.0
这是 Python 3.12 embeddable 与 onnxruntime 高版本的兼容性问题，不是系统环境问题

四、最终解决方案

4.1 核心修复命令

bash 复制代码

# 1. 先安装其他依赖
python -m pip install "numpy<2" soundfile librosa PyYAML supertonic

# 2. 必须降级 onnxruntime 到 1.17.0（关键步骤！）
python -m pip uninstall -y onnxruntime onnxruntime-gpu onnxruntime-directml onnxruntime-openvino
python -m pip install onnxruntime==1.17.0

4.2 验证修复

bash 复制代码

python -c "import onnxruntime; print('version:', onnxruntime.__version__)"
# 预期输出：version: 1.17.0

# 验证 TTS 功能
python -c "
from supertonic import TTS
tts = TTS(model_dir='assets', auto_download=False)
style = tts.get_voice_style('M1')
wav, dur = tts.synthesize('Hello world', 'en', style, 8, 1.05)
print(f'Generated {dur[0]:.2f}s audio, shape: {wav.shape}')
"
# 预期输出：Generated 1.23s audio, shape: (1, 54272)

4.3 注意事项

Windows 11 警告 ：运行时会提示 Unsupported Windows version (11)，这是 onnxruntime 1.17.0 的已知问题，不影响功能，可安全忽略。
numpy 版本 ：必须安装 numpy<2，numpy 2.x 可能与 onnxruntime 1.17.0 不兼容。
supertonic 版本要求 ：supertonic 1.3.1 在 metadata 中要求 onnxruntime>=1.19.0，但实际测试 1.17.0 可以正常运行，无需强制升级。

五、给 AI 的快捷指令

如果你是一名 AI Agent，遇到同样的问题，直接执行以下命令：

bash 复制代码

# 诊断：确认是 WinError 5
python -c "import ctypes, os; ctypes.CDLL(os.path.abspath('python/Lib/site-packages/onnxruntime/capi/onnxruntime_pybind11_state.pyd'))"
# 如果报错 [WinError 5]，继续下一步

# 修复：降级 onnxruntime
python -m pip uninstall -y onnxruntime onnxruntime-gpu onnxruntime-directml onnxruntime-openvino
python -m pip install onnxruntime==1.17.0 "numpy<2"

# 验证
python -c "import onnxruntime; print(onnxruntime.__version__)"

六、参考信息

onnxruntime 官方版本兼容性：https://onnxruntime.ai/docs/reference/compatibility.html
Python embeddable 文档：https://docs.python.org/3/using/windows.html#the-embeddable-package
相关 GitHub Issue：https://github.com/microsoft/onnxruntime/issues/25193

标签：Python, onnxruntime, Windows, 便携包, DLL, embeddable