症状：Windows 上打包完成了，但交给 Mac 用户后无法启动，或者程序启动后找不到项目数据。 最快解法：在 macOS 环境运行 PyInstaller 6.22.3，先用目录模式检查依赖和资源；验收通过后，再决定是否改成单文件。

研究生或博士生：需要把 Python 分析程序交给使用 Mac 的导师或合作者。 科研开发者：正在打包带 GUI、数据文件或原生依赖的项目。 高校技术支持人员：需要建立可重复的构建与验收流程。

先按交付对象选验收终点

PyInstaller 6.22.3 在 Mac 打包科研程序，第一步不是挑“最方便”的输出格式，而是确认构建平台和交付目标。PyInstaller 官方说明，程序会收集脚本所需的解释器、模块和库；跨操作系统交付时，应在目标操作系统对应的环境中构建，不能把 Windows 产物视为 Mac 应用。PyInstaller 官方平台与构建说明

先把“完成”拆成不同验收层级，避免把打包器没有报错误认为程序交付成功：

  • 课题组内部验收：指定 Mac 上能启动，GUI 交互正常，代表性样例能读入并产生预期结果。
  • 交给合作者使用：除上述检查外，还要说明输入文件、配置文件、输出位置和运行方式；最好由另一份项目副本或目标账户复核。
  • 公开分发：另行核对代码签名、公证及分发渠道要求。应用能运行、科研结果可复现、外部用户能顺利安装，是不同的验收结论。
如果目标是先验证“这个 Python 科研 GUI 能不能在 Mac 上工作”，优先选择 **macOS 构建、onedir 目录模式、通过验收后再考虑 onefile**。目录模式让依赖文件可检查；单文件只改变交付形态，不会自动补齐遗漏的模块，也不证明分析结果正确。PyInstaller 官方文档对目录模式和单文件模式的差异作了说明。([PyInstaller 官方模式说明](https://pyinstaller.org/en/stable/operating-mode.html))

构建前，先封存一份可回退的项目副本

不要直接在课题组唯一的工作目录里试打包。把代码复制到独立副本或版本控制分支，确保每次修改打包参数、资源路径或依赖后，都能回到一个已知可运行的状态。

在副本中记录这些构建信息，后续才能解释“同一份代码为什么在另一台 Mac 上行为不同”：

  • Python 版本、PyInstaller 版本及项目直接依赖；PyInstaller 官方文档页面标示为 6.22.3，本篇命令将版本明确固定，避免环境悄悄漂移。PyInstaller 6.22.3 官方变更记录
  • 构建 Mac 的系统与处理器架构，以及目标 Mac 的系统和架构；将这些信息写进构建记录，不要只记“Mac”。
  • 启动入口、GUI 框架、原生扩展和动态库；对延迟导入、插件加载或运行时拼接模块名的代码，单独列出需要检查的依赖。
  • 项目会读取的样例数据、模板、配置文件、模型文件和图标；为每项标注是否要随应用交付。
科研数据还要单独做使用边界检查：打包验证先用可公开或脱敏样例，不要将受试者数据、未公开课题数据、凭据或个人配置一并放进应用。数据文件即使方便放入包内，也不代表你有权把它交给合作者或外部用户。

建立干净环境，再生成可检查的目录包

在准备好的 macOS 环境中，进入项目副本，创建隔离的 Python 环境并安装项目依赖。确认原始脚本或 GUI 程序先能在这个环境里运行，再安装并固定 PyInstaller：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install PyInstaller==6.22.3

若项目没有 requirements.txt，先根据实际项目整理并记录依赖，不要为了让打包通过而临时从其他环境复制不明版本的库。PyInstaller 的构建结果取决于分析时可见的模块和二进制依赖；运行环境中“刚好存在”的文件，可能掩盖项目声明不完整的问题。官方命令行文档列出了目录模式、单文件模式等构建选项。PyInstaller 官方命令选项

从目录模式开始构建。将 analysis_gui.py 换成你的入口文件；--windowed 用于 GUI 程序，若是命令行分析工具，可先去掉它，以便在终端观察诊断输出。

python -m PyInstaller --onedir --windowed --name LabAnalysis analysis_gui.py

PyInstaller 的命令行文档将 --onedir 定义为目录包，且它是默认模式；--onefile 才是单文件包。使用目录模式时，先查看 dist/LabAnalysis 中实际收集到的文件，再决定是否需要调整打包配置。

当程序缺少数据文件时，先核对“文件有没有被收集”和“运行时代码从哪里找它”，不要立刻把整个项目目录塞进产物。固定资源可用 --add-data 明确加入，例如：

python -m PyInstaller --onedir --windowed \
  --add-data "resources:resources" \
  --name LabAnalysis analysis_gui.py

macOS 下示例中的冒号用于分隔源路径与目标目录；若资源清单较长、需要重复构建，转为维护 spec 文件会更清晰。PyInstaller 文档说明，datas 用于指定非二进制数据文件；资源在包内的目标位置应与程序运行时的查找方式一致。官方数据文件与 spec 配置说明

对于 Python 包内部自带的模板或数据，不要假设导入包时它们也会自动进入产物。明确声明数据后，再让代码从稳定的包资源接口或与 __file__ 对应的位置读取；PyInstaller 的运行时路径说明介绍了打包后基于 __file__ 定位资源的方式。

注意：模板、参考数据等随包提供的只读资源，与用户新生成的结果文件不是一类东西。不要把可变输出写进应用包的资源路径；让用户选择输出目录，或写到明确可写的用户目录，并检查目标位置不存在时程序如何提示。

如果目录包里仍有缺失模块，查看构建日志并制作最小复现：记录导入模块、报错位置和触发步骤，再逐项补充 hidden-import、hook 或二进制依赖。PyInstaller 文档指出，hook 可用于处理常规分析难以发现的包依赖；不要用一次启动成功代替对插件、延迟导入和原生库的检查。[PyInstaller 官方 hook 机制说明](https://www.pyinstaller.org/en/stable/hooks.html)

从 Finder 启动，核对输入、路径与科研输出

终端里运行成功只说明当前启动方式下程序可运行，不等于交付给导师或合作者时也能正常使用。将目录包复制到单独位置，从 Finder 启动一次，再按同一份样例完成以下复测：

  1. 检查 GUI 交互：窗口是否出现，文件选择器、菜单、取消操作和错误提示是否正常；确认关闭窗口后进程能否正常退出。
  2. 检查输入路径：分别用应用内选择文件和项目预期支持的其他入口读取样例；避免依赖“当前工作目录刚好是项目根目录”的隐式假设。
  3. 检查资源路径：测试模板、配置和参考文件是否被找到；若资源来自包内，确认运行代码定位的是包内资源，而非构建机上的绝对路径。
  4. 检查输出位置：保存结果到用户指定目录，确认文件实际生成、文件名合理，应用不会尝试修改只读应用包中的内容。
  5. 检查科研结果：用同一份已知输入运行原始 Python 项目和打包程序，对照关键输出文件及课题关心的结果；若不一致，分别检查数据读取、随机性或配置差异，以及打包依赖问题。
  6. 留存复测证据：记录构建命令、依赖清单、样例标识、关键输出和日志。去掉敏感数据本体，只保留足以复核的元信息。
找不到数据文件时，按三层定位：打包清单中是否包含它；程序在打包状态下解析出的路径是否正确；应用运行账户是否有权限读取该位置。PyInstaller 对数据文件的说明强调，资源在包内的目标目录应与运行时代码采用的定位方式相匹配。

通过目录验收后，再分支选择交付形式

下面的条件分支用来决定是否切换模式；没有满足前提时，回退到目录包继续定位，不要为了“看起来像正式应用”跳过复测。

  • 若目标是课题组内部验收，且需要逐项检查缺失依赖：选 onedir。目录结构便于核对模块、动态库和数据资源；出现故障时，更容易把具体文件与错误关联。
  • 若合作者确实需要单个文件，且目录包已完成相同样例的复测：再试 onefile。PyInstaller 会在运行时将相关支持文件解压到临时目录，因此启动过程和临时文件行为与目录模式不同；打包模式切换后，重新测试资源读取、崩溃后清理、GUI 启动与结果输出。
  • 若程序需要写入长期保留的数据、用户配置或分析结果：无论选择哪种模式，都将可变内容放在应用包之外，并确认目录包和单文件包使用同一套明确的输入、输出路径规则。
  • 若要求面向校外或公众发布：暂停“只验收能否运行”的判断，先确认签名、公证、目标系统和分发渠道要求，再形成独立发布流程。
目录模式评分：**依赖可见性高，初次排错更容易；分发时需要保留目录结构。**单文件模式评分：**交付入口更集中，但会引入临时解包行为；不适合作为首次定位依赖问题的捷径。**这是基于官方描述的操作决策，不是对某个项目构建速度或成功率的实测排名。

将“能运行、可复现、可分发”分开签字

完成 Finder 启动测试后，让另一份项目副本或目标 Mac 账户执行交叉复核。复核者不应依赖构建者机器上的工作目录、个人配置或未记录的数据文件；应按交付说明重新选择输入，确认代表性分析、结果文件和日志都符合预期。

可运行：应用能打开，基本交互和文件读写路径有效。 可复现：同一份受控输入与记录的环境下，关键科研输出符合项目预先定义的比较标准。这个标准应由项目负责人确定，不能由“PyInstaller 已成功生成产物”替代。 可分发：签名、公证和外部分发准备已按目标渠道检查。Apple 将应用签名与公证列为分发流程中的安全环节；直接分发的软件应依其官方要求选择相应签名方式和后续操作。Apple 官方 macOS 软件分发概览

因此，内部测试阶段不必把“还没公证”误判为分析程序无法运行；反过来，若应用要交给不熟悉开发流程的外部用户，也不能把内部样例通过当作已经完成了公开发布。签名或公证遇到问题时，应查看 Apple 的当前要求和提交日志，不要绕过系统安全检查。

如果你正在评估目标 Mac 的构建环境，可先查看 MACGPU 的 Mac 环境入口；若计划自购一台专用机器，再按项目的目标架构和实际使用方式核对 Mac 选购信息，不要把设备选型等同于应用验收。

常见问题：把剩余风险在交付前说清

Windows 上打包，能不能直接给 Mac 使用？ 不能把 Windows 生成的产物当作 macOS 应用交付。分别在目标系统对应的环境中构建，并分别检查系统依赖与原生扩展；如果课题组需要同时交付 Windows 和 Mac 版本，应保留两套构建记录和各自的验收结果。

打包后程序找不到科研数据文件，先查什么？ 先检查资源是否进入产物，再检查包内相对路径与程序定位代码是否匹配；最后检查目标用户对文件和目录的读取权限。固定模板可以随应用打包，用户新生成的数据则应写到明确可写的位置，避免误写入应用包。

onedir 和 onefile 怎么选？ 首次打包优先 onedir，先把依赖和资源问题定位清楚。只有目录包通过样例验收、且交付对象确实需要单一文件时，再评估 onefile；模式改变后要重新检查解包行为、数据路径和输出文件，不能沿用旧的验收结论。

Mac 应用要签名和公证吗？ 按用途区分。课题组内部测试主要核验运行和科研结果；向外部用户分发时，应根据是否通过 Mac App Store 以及目标分发渠道，查阅 Apple 当前的签名、公证要求。PyInstaller 负责构建程序产物，并不代替外部分发验收。

如果你目前只能用 Windows 或 Linux，临时拼接虚拟环境、依赖和文件路径，往往会多出跨平台差异、资源遗漏和目标 Mac 复测缺口；长期稳定地重复构建，则应评估自购 Mac 是否更适合。如果只是阶段性需要生成 macOS 产物并在真实 Mac 上复测，租用 MACGPU 的远程 Mac 可让你在 macOS 环境中完成构建与验收；开始前先确认项目数据能否上传、访问方式是否符合课题组要求，以及远程环境是否满足目标架构和系统条件。