在 UV 的开发依赖环境中使用 PyInstaller 打包 Python 项目时，需注意环境隔离、依赖处理、路径配置等问题，以下是关键注意点及解决方案：

确保在 UV 虚拟环境中运行 PyInstaller

uv tree

安装 PyInstaller 到 UV 开发环境

PyInstaller 需作为开发依赖安装在 UV 环境中，否则无法识别环境内的第三方库。

作为开发依赖安装（推荐，不影响生产环境）

uv add --dev pyinstaller

安装后，UV 会将其记录到 pyproject.toml 和 uv.lock 中，确保团队成员环境一致。

–dev 参数的说明

当使用 uv add 命令安装库时，加上 –dev 参数，UV 会将该库记录到 pyproject.toml 的 “开发依赖” 配置中，而非 “运行时依赖”。

使用–dev参数的好处：

• 1. 环境隔离：生产环境安装依赖时，不会安装这些开发工具，减少冗余；
• 2. 依赖清晰：通过配置文件可明确区分 “项目必须的依赖” 和 “开发辅助工具”；
• 3. 团队协作：新成员克隆项目后，可通过命令一键安装所有开发依赖，快速搭建开发环境。

后来在其他计算机上克隆本项目（包含 pyproject.toml）时，安装项目的所有开发依赖（如测试工具、代码规范工具），可运行：

安装项目的所有开发依赖

uv sync --dev

uv sync 是 UV 的 “同步依赖” 命令，默认仅安装 project.dependencies 中的运行时依赖；

加上 –dev 后，会同时安装
project.optional-dependencies.dev 中的所有开发依赖。

使用uv run pyinstaller命令打包

uv run pyinstaller -F convert_docx_to_md.py --name convert_docx_to_md

-F 全称 –onefile，表明将所有代码、依赖库和资源文件打包成一个单独的可执行文件（而非多个文件或文件夹），便于分发和使用。

convert_docx_to_md.py 是需要被打包的 Python 源文件

–name convert_docx_to_md 指定打包后生成的可执行文件的名称为 convert_docx_to_md

处理动态导入或隐藏依赖（打包提示缺少库）

若项目中使用 importlib 动态导入模块，或依赖通过非标准方式加载（如自定义路径），PyInstaller 可能无法自动检测到这些依赖，导致打包后运行报错。

解决方案：

• 在 pyinstaller 命令中通过 –hidden-import <模块名> 手动指定隐藏依赖，例如：

uv run pyinstaller -F main.py --hidden-import=module.submodule

清理缓存和重建环境（遇到奇怪问题时）

若打包出现依赖版本冲突、路径混乱等难以排查的问题，可利用 UV 的高效环境管理能力重置环境：

删除项目下 .venv目录

# 重新创建环境并安装依赖（根据 pyproject.toml 重建）

uv sync dev