Python打包进阶:怎么正确包含图片、配置文件等外部资源

竹里
竹里
发布时间:2026-11-18| 7人浏览过
原创

详细解析Python打包时正确包含图片、模板与配置文件的方案,涵盖pyproject.toml包数据配置、importlib.resources运行时安全定位以及PyInstaller环境适配。

很多 Python 开发者在本地开发脚本时,使用 open("config.yaml") 或相对路径读取图片可以正常运行,但一旦将项目打包成 Wheel 分发安装,或使用 PyInstaller 打包成单文件可执行程序后,程序便会立刻抛出 FileNotFoundError。这个问题的根源在于:Python 默认的构建流程只会自动收集 .py 源码文件,而外部静态资源不仅需要在构建配置中显式声明包含,更需要在代码中使用与运行环境解耦的定位方式去加载。

为什么外部资源会在打包后“失踪”?

在理解解决方法前,需要理清两种常见的路径解析陷阱。第一种是依赖当前工作目录(CWD),例如直接写相对路径 open("assets/logo.png")。此时文件查找依赖于终端执行命令时所在的目录,用户在任何其他目录下运行程序都会导致路径断裂。第二种是依赖 __file__ 拼接物理路径,这在源码处于普通文件夹时有效,但当项目被安装为 zip 压缩包格式的 Wheel,或者被 PyInstaller 打包进虚拟内存临时目录时,基于物理相对位置的假设就会失效。

Python打包进阶:怎么正确包含图片、配置文件等外部资源
图1:三种资源访问方式的原理解析与可靠性对比

规范的工程目录组织

为了让打包工具正确识别资源归属,最稳妥的做法是将非代码资源放在 Python 模块自身的命名空间内,而不是散落在与代码平级的根目录中。推荐使用现代标准的 src/ 布局:

my_project/
├── pyproject.toml              # 现代构建配置文件 (PEP 621)
├── README.md
└── src/
    └── my_package/             # 顶层包目录
        ├── __init__.py
        ├── core.py
        └── assets/             # 资源子目录(作为包内数据)
            ├── config.yaml
            ├── template.html
            └── logo.png

将资源置于 my_package/assets/ 下,其在逻辑上就变成了 my_package 的内部组成部分,无论是 setuptools、hatchling 还是 flit,都可以通过模块路径轻松匹配并打包这些文件。

在构建配置中声明包含规则

仅把文件放入目录还不够,构建工具默认可能只抓取 *.py 文件。现代 Python 打包统一采用 pyproject.toml。以下以最常见的 setuptools 与 hatchling 为例说明如何配置。

基于 setuptools 的配置

在 pyproject.toml 中添加 [tool.setuptools.package-data],明确指出哪些包路径下的哪些后缀应该被纳入打包:

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "0.1.0"
description = "包含外部静态资源的示例包"
readme = "README.md"
requires-python = ">=3.9"

[tool.setuptools.packages.find]
where = ["src"]

# 显式声明包含的非代码资源
[tool.setuptools.package-data]
"my_package" = [
    "assets/*.yaml",
    "assets/*.png",
    "assets/*.html",
]
注意事项:避免仅依赖根目录下的 MANIFEST.in。虽然 MANIFEST.in 能够确保源码分发包(sdist)包含文件,但构建二进制 Wheel 包时,仍需要 package-data 保证资源被实际拷贝进轮子内。
Python打包进阶:怎么正确包含图片、配置文件等外部资源
图2:从项目结构规整到构建验证的标准操作步骤

运行时安全读取:使用 importlib.resources

在 Python 3.9 及更高版本中,标准库中的 importlib.resources.files 是读取包内资源的首选方式。它消除了废弃的 pkg_resources 带来的性能负担,也避免了直接使用 __file__ 在特殊归档中的隐患。

读取文本或二进制文件

from importlib.resources import files
import yaml

def load_default_config():
    # 获取资源引用:files("包名").joinpath("相对路径")
    resource = files("my_package").joinpath("assets/config.yaml")
    
    # 直接以文本方式读取内容
    content = resource.read_text(encoding="utf-8")
    return yaml.safe_load(content)

def get_logo_bytes() -> bytes:
    resource = files("my_package").joinpath("assets/logo.png")
    # 直接读取二进制数据
    return resource.read_bytes()

需要真实文件系统路径时的处理

如果外部底层 C 扩展库(例如 OpenCV 或某些 SQLite 接口)必须接收一个操作系统物理路径(字符串格式的 path),可以使用 as_file 上下文管理器:

from importlib.resources import files, as_file

def initialize_database():
    resource = files("my_package").joinpath("assets/template.sqlite3")
    
    # as_file 会保证在上下文中提供一个实际的文件系统路径
    # 如果资源位于 zip 中,它会临时解压并在退出上下文后自动清理
    with as_file(resource) as file_path:
        connect_native_driver(str(file_path))

兼顾 PyInstaller 独立可执行程序打包

如果目标不是分发 pip 包,而是通过 PyInstaller 打包成单文件(--onefile)运行,机制会有所不同。在 PyInstaller 运行时,所有资源会被临时解压到 sys._MEIPASS 目录中。

Python打包进阶:怎么正确包含图片、配置文件等外部资源
图3:Wheel 包与 PyInstaller 单文件打包的生命周期流转对照

PyInstaller 命令行参数指定资源

在执行打包命令时,必须通过 --add-data 参数将资源加入。注意,Windows 下的分隔符为分号(;),而 Linux 与 macOS 下的分隔符为冒号(:):

# Linux / macOS 下示例
pyinstaller -F main.py --add-data "src/my_package/assets:my_package/assets"

# Windows 下示例
pyinstaller -F main.py --add-data "src/my_package/assets;my_package/assets"

编写通用路径适配器

为了让一套代码既能在源码开发时运行,又能在 PyInstaller 单文件打包后正常工作,通常在代码中编写一个路径解析封装:

import sys
from pathlib import Path

def get_resource_path(relative_path: str) -> Path:
    """获取资源文件的绝对路径,兼容 PyInstaller 与源码开发环境"""
    if hasattr(sys, "_MEIPASS"):
        # PyInstaller 打包后的临时解压目录
        base_path = Path(sys._MEIPASS)
    else:
        # 源码开发时的基准目录
        base_path = Path(__file__).resolve().parent
        
    return base_path / relative_path

验证构建结果与排查总结

完成配置后,务必在发布前检查构建产物。可以使用官方标准工具 build 进行打包:

# 1. 安装构建工具
pip install build

# 2. 执行打包生成 wheel 与 sdist
python -m build

# 3. 检查 Wheel 内包含的文件列表(无需手动解压)
python -m zipfile -l dist/my_package-0.1.0-py3-none-any.whl

在 zipfile 列出的清单中,必须能够看到 my_package/assets/config.yaml 等静态资源。如果清单中只有 .py 文件,说明 pyproject.toml 中的匹配通配符或包路径存在书写偏差。

Python打包进阶:怎么正确包含图片、配置文件等外部资源
图4:构建产物与运行时路径问题排查决策树
场景 推荐声明配置 标准代码加载 API 主要陷阱与注意事项
标准模块分发 (Wheel) pyproject.toml 中的 [tool.setuptools.package-data] importlib.resources.files() 避免写纯相对路径;避免遗漏通配符后缀。
单文件可执行程序 (PyInstaller) --add-data "src:dest" 参数注入 封装检测 sys._MEIPASS 的工具函数 跨平台路径分隔符不同(Windows 分号,Unix 冒号)。
C 扩展/原生库调用 同上 importlib.resources.as_file() 上下文 退出上下文后临时提取的文件可能被清理,切勿缓存路径。

正确包含外部资源的关键在于分工清晰:构建配置负责将静态文件准确打入 Wheel 或二进制分发包,而业务代码则借助 importlib.resources 与 sys._MEIPASS 适配层抹平运行环境的物理路径差异。遵循这套规范,即可彻底告别打包后资源丢失与路径定位异常的问题。

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。