Python打包exe包含图片、配置文件等资源文件的正确方法

使用 PyInstaller 将 Python 程序打包为单文件（--onefile）可执行程序后，双击运行常出现 FileNotFoundError: [Errno 2] No such file or directory。这一问题的根源在于两个层面：一是打包工具默认只收集 Python 字节码，未自动把图片、图标、音频及 JSON 等非代码资源打包进程序；二是单文件 exe 在运行时会被操作系统解压到随机命名的临时目录（sys._MEIPASS），而代码中若直接使用相对路径，会以快捷方式或当前启动位置作为工作目录，导致资源寻址失效。要彻底解决该问题，必须同时实现“代码层动态寻址”与“打包层资源映射”，并对只读资源与可变配置实行读写分离。

一、单文件打包后常规相对路径失效的原理解析

在未打包的开发阶段，我们在命令行或编辑器中执行 python main.py，Python 解释器所在的工作目录通常就是项目工程的根目录。此时，代码中诸如 open("assets/logo.png") 或 open("config.json") 的代码可以通过相对路径顺利读取文件。

但当使用 pyinstaller -F（单文件模式）将整个程序打包为一个单独的 .exe 文件后，运行环境发生了根本性变化：

• 运行时临时解压机制：单文件可执行文件本质上是一个自解压封装包。当用户双击运行 app.exe 时，内置的引导加载器（Bootloader）会在操作系统的临时目录（在 Windows 下一般形如 AppData/Local/Temp/_MEIxxxxxx）中创建一个独立沙盒目录，并将打包在 exe 内部的所有依赖库、字节码与静态资源实时解压至该目录下。
• 工作目录漂移现象：操作系统的“当前工作目录”（Current Working Directory, CWD）由启动方式决定。如果用户在桌面为 app.exe 创建了一个快捷方式并双击启动，或者在其他路径通过命令行调用该 exe，程序的 CWD 往往是桌面或调用路径，而不是解压目录。
• 寻址断裂点：若代码中依旧直接书写相对路径 open("assets/logo.png")，Python 会在 CWD（即桌面）中寻找 assets/logo.png，自然无法找到解压在临时目录中的真实文件，从而抛出典型的 FileNotFoundError。

为了让代码知道被解压后的资源究竟位于何处，PyInstaller 在运行时向 Python 的 sys 模块注入了一个专用全局属性 sys._MEIPASS。该属性记录的就是当前程序运行时所在的临时解压绝对目录。当程序运行完毕并退出后，引导程序会自动清理并删除该临时文件夹。

二、核心实施第一步：编写通用的资源动态寻址函数

要让同一份代码既能在本地开发环境中直接运行调试，又能在打包成 exe 后精准命中临时解压目录，必须在代码层建立统一的路径解析入口，而不是在业务代码中各处硬编码或手动判断。

推荐在项目中定义一个标准的 resource_path() 辅助函数：

import os
import sys

def resource_path(relative_path: str) -> str:
    """
    获取资源文件的绝对路径
    兼容本地直接运行调试与 PyInstaller 打包后的运行环境
    """
    try:
        # PyInstaller 单文件打包后，运行时会将资源解压到 sys._MEIPASS 目录
        base_path = sys._MEIPASS
    except AttributeError:
        # 本地开发环境下无 _MEIPASS 属性，采用当前脚本所在文件的绝对父目录
        base_path = os.path.dirname(os.path.abspath(__file__))

    return os.path.normpath(os.path.join(base_path, relative_path))

在业务代码中替换路径引用

完成寻址函数的定义后，项目中所有加载外部静态资源的地方，均需通过 resource_path() 进行包裹。以下是常见应用场景的写法范例：

import json
from PIL import Image

# 场景 1：使用 PIL 加载界面图像
icon_path = resource_path("assets/icon.png")
icon_img = Image.open(icon_path)

# 场景 2：读取内置的默认 JSON 配置文件
config_template_path = resource_path("config/default_settings.json")
with open(config_template_path, "r", encoding="utf-8") as f:
    default_config = json.load(f)

# 场景 3：Tkinter / PyQt 窗体图标设置
# window.iconphoto(False, PhotoImage(file=resource_path("assets/app.png")))

三、核心实施第二步：在打包配置中正确声明资源映射

即便代码中使用了 resource_path()，如果打包阶段未告知 PyInstaller 需要将哪些静态文件随同打包，解压目录中依然不会有这些文件。我们需要显式配置资源映射关系。

方法一：通过命令行参数 --add-data 打包

PyInstaller 提供了 --add-data 参数，其格式为 --add-data "<源路径><系统分隔符><目标解压路径>"。

参数中的目标解压路径（即分隔符右侧内容）表示解压到 sys._MEIPASS 根目录下的相对文件夹：

• --add-data "assets;assets"：将本地的 assets 目录整包复制到 sys._MEIPASS/assets/。代码中使用 resource_path("assets/logo.png") 能够无缝匹配。
• --add-data "config/default.json;config"：将单个文件放入临时解压目录下的 config/ 文件夹中。
• --add-data "assets/icon.png;."：若目标写为点 .，则文件会被解压在临时目录根部，代码则需对应写为 resource_path("icon.png")。生产实践中建议保持原始目录结构一致，避免路径混乱。

方法二：使用 .spec 配置文件维护资源列表（工程化推荐）

当项目包含的图片、字体、配置文件较多时，命令行参数会变得异常冗长且难以版本化。此时推荐直接维护由 PyInstaller 生成的 .spec 规范文件。

1. 首次生成 spec 文件：

pyi-makespec -F -w main.py

2. 打开生成的 main.spec，找到 Analysis 对象下的 datas 属性，将其补充为元组列表 [(源路径, 目标路径)]：

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

added_files = [
    ('assets', 'assets'),                       # 打包整个 assets 文件夹
    ('config/default_settings.json', 'config')  # 打包特定配置文件
]

a = Analysis(
    ['main.py'],
    pathex=[],
    binaries=[],
    datas=added_files,                          # 此处注入资源映射表
    hiddenimports=[],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='MyApp',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=False,   # 设置为 False 则不弹出黑色控制台终端
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
    icon='assets/app.ico'  # 程序本身的主图标（exe 文件图标）
)

3. 后续打包只需执行 spec 文件即可，方便集成进自动化构建流程：

pyinstaller main.spec

四、关键架构边界：只读内置资源与运行时持久化配置的读写分离

许多开发者在解决了图片读取问题后，遇到另一个严重的隐蔽故障：在程序中修改了配置文件，但程序重启后配置又恢复成了初始状态，或者直接报错权限拒绝。

这是因为单文件 exe 运行时的 sys._MEIPASS 临时目录具有严格的只读属性与临时生命周期：

• 临时目录受操作系统管理，进程退出瞬间，临时目录下的所有内容连同修改后的文件会被操作系统一次性销毁。
• 因此，严禁直接向 resource_path() 指向的内置文件执行写入操作。

标准的配置初始化与读写范式

成熟的桌面程序应采用“只读模版内置，用户配置外置”的读写分离架构。具体逻辑如下：

1. 在 exe 内部封装一份只读的默认配置模版（例如 default_settings.json）。
2. 程序启动时，检查外部可写持久化目录（例如 exe 同级目录或操作系统的 %APPDATA% 目录）中是否存在用户的 user_config.json。
3. 如果外部不存在，则利用 resource_path() 读取内置模版，并在外部写出一份初始化的用户配置；后续所有的修改操作均针对该外部文件进行。

import os
import sys
import json
import shutil

def get_app_dir() -> str:
    """获取可执行文件所在的实际物理目录（用于存放持久化数据）"""
    if getattr(sys, 'frozen', False):
        # 打包运行环境：获取 exe 所在的实际物理目录，而非临时解压目录
        return os.path.dirname(os.path.abspath(sys.executable))
    else:
        # 开发调试环境：当前脚本所在目录
        return os.path.dirname(os.path.abspath(__file__))

def init_user_config() -> dict:
    """读写分离的配置管理：确保用户配置持久化保存"""
    app_dir = get_app_dir()
    user_config_path = os.path.join(app_dir, "config.json")

    # 若外部配置尚不存在，从内置只读资源中复制一份模板
    if not os.path.exists(user_config_path):
        template_path = resource_path("config/default_settings.json")
        try:
            shutil.copyfile(template_path, user_config_path)
        except Exception as e:
            # 容错：若无法直接复制，手动读写生成
            with open(template_path, "r", encoding="utf-8") as f_in:
                default_data = json.load(f_in)
            with open(user_config_path, "w", encoding="utf-8") as f_out:
                json.dump(default_data, f_out, indent=2, ensure_ascii=False)

    # 业务统一读写外部持久化配置文件
    with open(user_config_path, "r", encoding="utf-8") as f:
        return json.load(f)

def save_user_config(config_data: dict) -> None:
    """保存用户修改后的配置"""
    user_config_path = os.path.join(get_app_dir(), "config.json")
    with open(user_config_path, "w", encoding="utf-8") as f:
        json.dump(config_data, f, indent=2, ensure_ascii=False)

五、打包结果验证与常见问题自查清单

在完成代码改造与打包声明后，可以通过以下步骤进行最终的验证与排查。

验证与调试技巧

• 保留调试窗口：排查阶段打包时暂不要添加 -w 或 --noconsole 参数。保留黑色的控制台窗口，这样一旦出现路径错误，能够第一时间在终端中看到完整的 Traceback 报错栈。
• 打印临时目录清单：在程序入口加入调试输出：

  if getattr(sys, 'frozen', False):
      print("运行时解压目录 sys._MEIPASS:", sys._MEIPASS)
      print("解压目录内容清单:", os.listdir(sys._MEIPASS))

  通过直观打印可以确认资源文件是否被解压到了预期的层级。
• 多入口测试：不要只在 dist 目录下双击测试。将生成的 exe 拷贝到桌面、C 盘根目录或带有中文/空格的路径下分别运行，确认在各种极端工作目录下均能稳定定位资源。

常见问题速查表

通过“resource_path() 适配解压目录”、“--add-data / spec 声明资源映射”以及“只读资源与外部配置读写分离”这套组合方案，可以彻底根治单文件 exe 打包中资源文件丢失与无法持久化的问题，构建稳定可靠的 Python 桌面分发程序。