Python 便携版配置与使用教程

Embedded Python 默认：

• ❌ 不加载 Lib
• ❌ 不加载 site-packages
• ❌ 不允许 pip

这是通过 python310._pth 控制的。

_pth 是什么？

它是：

Python 启动时的'白名单路径表'

• 只加载你写进去的路径
• 绝不偷偷读系统环境

📌 这就是它'便携 + 隔离'的核心

四、配置 Embedded Python（最关键部分）

✅ Step 1：手动创建目录（必须）

在 python_embed 目录下，新建：

python_embed/
├─ Lib/
│ └─ site-packages/

👉 Python 不会帮你建，你要自己建

✅ Step 2：编辑 python310._pth

打开：

python_embed\python310._pth 

把内容 完全改成下面这样（照抄）：

python310.zip . Lib Lib\site-packages import site 

每一行的意义

⚠️ 没有 import site = 一切白搭

五、给 Embedded Python 安装 pip（正确方式）

❌ 为什么 ensurepip 不存在？

Embedded Python 官方移除了：

• ensurepip
• venv

👉 所以你看到：

No module named ensurepip 

是 正常现象

✅ 正确解法：get-pip.py（官方方案）

Step 1：下载 get-pip.py

地址：

https://bootstrap.pypa.io/get-pip.py 

放到：

python_embed\get-pip.py 

Step 2：用'便携 python.exe'运行

cd D:\示例路径\python_embed
.\\python.exe get-pip.py 

成功后会安装：

• pip
• setuptools
• wheel

到：

python_embed\Lib\site-packages\ 

Step 3：验证 pip

.\\python.exe -m pip --version 

输出示例：

pip 24.x from D:\示例路径\python_embed\Lib\site-packages\pip 

✅ 说明成功

六、在便携 Python 中安装第三方库（正确姿势）

⚠️ 永远用你的 python.exe

.\\python.exe -m pip install faster-whisper 

.\\python.exe -m pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu121 

❌ 不要用：

pip install xxx 

七、如何'确保不用系统 Python'（核心技巧）

方法一：始终用绝对路径

D:\示例路径\python_embed\python.exe app\main.py 

方法二：启动脚本（推荐）

run.bat（标准写法）

@echo off
set BASEDIR=%~dp0
set PYTHONHOME=%BASEDIR%python_embed
set PYTHONNOUSERSITE=1
set PATH=%BASEDIR%python_embed;%BASEDIR%python_embed\Scripts;%PATH%
"%BASEDIR%python_embed\python.exe" app\main.py
pause

自检（一定要做）

在 main.py 里：

import sys
print(sys.executable)

必须输出：

D:\示例路径\python_embed\python.exe 

八、为什么'没有 Lib 也能 import os/json？'

因为：

• 标准库在 python310.zip
• Python 会自动从 zip 里加载

📌 这是 Embedded Python 的设计亮点

九、推荐的'便携 AI 项目结构'（对标 ComfyUI）

项目根目录/
├─ python_embed/
│ ├─ python.exe
│ ├─ python310.zip
│ ├─ python310._pth
│ └─ Lib/
│   └─ site-packages/
├─ ffmpeg/
│ └─ ffmpeg.exe
├─ app/
│ ├─ main.py
│ ├─ gui.py
│ └─ asr_engine.py
├─ run.bat
└─ README.md

十、发布前'自检清单'（非常重要）

• sys.executable 指向便携 python
• 删除系统 Python，程序仍能跑
• pip 安装的库都在 Lib/site-packages
• _pth 中有 import site