• 本机运行
• 迁移到其他电脑
• 位数不同的处理
• 在线 / 离线 两种方式
• uv 是否必须安装的边界

全文按“操作流程 + 规则说明”来写，适合长期复用。

Python 项目跨电脑运行与迁移流程（含位数差异、在线与离线）

前提条件

• 项目目录中已经存在 requirements.txt
• 项目通过 python main.py 或类似方式启动
• 使用 Windows 环境为例
• 工具以 uv + venv + pip 为主

一、本机首次运行流程（标准做法）

1. 安装 Python 解释器

推荐统一 Python 大版本，例如：

uv python install 3.11.6

说明：

• 不必锁死到某个补丁位
• 大版本一致即可

2. 创建虚拟环境

在项目根目录：

uv venv --python 3.11.6

激活环境：

.venv\Scripts\activate

确认解释器来自虚拟环境：

where python
python -V

3. 补齐基础构建工具（关键步骤）

python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel

说明：

• uv 创建的是精简环境
• wheel 缺失会导致 C 扩展包构建失败
• 这是 Windows 下的必做步骤

4. 安装依赖

python -m pip install -r requirements.txt

若失败：

• 检查包名是否真实存在于 PyPI
• 检查是否触发源码编译
• 记录失败包名，后续迁移会用到

5. 本机运行验证

python main.py

确认功能可用后再进入迁移阶段。

二、迁移的基本原则（必须先理解）

原则 1

永远不复制 .venv 到另一台电脑

• venv 内含路径、架构、动态库绑定
• 只能在创建它的机器上可靠运行

原则 2

迁移的对象是代码 + 依赖声明，不是环境

迁移内容：

• 项目源码
• requirements.txt
• 可选 .python-version

原则 3

Python 位数优先级高于 Python 版本

• 3.11.6 64 位
• 3.11.6 32 位

对依赖来说是两个完全不同的平台。

三、位数不同的处理逻辑（核心）

1. 64 位 → 64 位

• 正常迁移
• 风险最低

2. 64 位 → 32 位

这是硬边界场景：

• 所有带二进制扩展的包必须有 win32 支持
• 必须在 32 位环境中重新安装依赖
• 不能复用 64 位任何构建产物

四、在线迁移流程（目标机可联网）

适用场景

• 目标机能访问 PyPI
• 允许重新下载依赖

步骤 1：拷贝项目代码

拷贝：

• 项目源码
• requirements.txt

不拷贝：

• .venv

步骤 2：在目标机安装 Python

必须与目标机位数一致：

• 64 位系统 → 64 位 Python
• 32 位系统 → 32 位 Python

确认位数：

python -c "import struct; print(struct.calcsize('P') * 8)"

步骤 3：创建虚拟环境

uv venv --python 3.11.6
.venv\Scripts\activate

步骤 4：补齐工具链

python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel

步骤 5：安装依赖并运行

python -m pip install -r requirements.txt
python main.py

五、离线迁移流程（目标机无互联网）

这是最容易踩坑的部分。

核心结论

离线部署必须在“同位数、可联网的中转机”上准备依赖。

• 64 位中转机只能给 64 位用
• 32 位中转机才能给 32 位用

阶段一：准备中转机

要求：

• 操作系统位数 = 目标机
• Python 版本 = 目标机
• 可联网

阶段二：下载依赖（不安装）

在中转机项目目录：

mkdir offline_pkgs
python -m pip download -r requirements.txt -d offline_pkgs

这一步的意义：

• 提前验证是否有可用 wheel
• 提前暴露 32 位不支持的问题

阶段三：模拟离线安装验证

python -m pip install --no-index --find-links=offline_pkgs -r requirements.txt

能成功，说明离线部署可行。 失败，说明该项目不适合该位数环境。

阶段四：拷贝到目标离线机

拷贝内容：

• 项目源码
• requirements.txt
• offline_pkgs/

阶段五：目标机离线安装

uv venv --python 3.11.6
.venv\Scripts\activate
python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel
python -m pip install --no-index --find-links=offline_pkgs -r requirements.txt
python main.py

六、uv 是否必须安装

结论

• 运行阶段不需要 uv
• 创建 / 重建环境阶段才需要 uv

说明：

• 虚拟环境激活后
• 使用的是 .venv 内的 python
• uv 不参与运行

如果目标机已经有 Python：

• 可以不用 uv
• 用 python -m venv 也能完成部署

七、工程经验总结

• 迁移的是代码和依赖声明
• 环境必须在目标机重建
• 位数不同是物理边界
• 离线部署的难点在于“是否存在对应架构的 wheel”
• uv 是开发工具，不是运行时依赖

一句话版本：

Python 项目迁移的本质不是拷贝环境，而是重建环境。