importlib.resources更可靠，因其是Python标准库模块、零依赖、无副作用，且天然支持zip包和冻结环境；而pkg_resources已被弃用，易在虚拟环境或PEP 517构建中失效，并引发DistributionNotFound或FileNotFoundError。

为什么 importlib.resources 比 pkg_resources 更可靠

因为 pkg_resources 在 Python 3.9+ 中已显式标记为“不推荐使用”，且依赖 easy_install 机制，容易在虚拟环境或 PEP 517 构建中失效；importlib.resources 是标准库模块，零依赖、无运行时副作用，且与 importlib.metadata 协同良好。

常见错误现象：pkg_resources.DistributionNotFound 或资源路径拼接后 FileNotFoundError —— 多数源于开发者手动拼接 __file__ 路径，而该路径在 zipimport、冻结可执行文件（如 PyInstaller）或命名空间包中根本不可靠。

• 始终用资源名（字符串），而非文件系统路径
• 资源名必须是相对于包的相对路径，不以 / 开头，且用 / 分隔（非 os.sep）
• 不支持通配符或递归遍历；需明确指定文件名

files() 是 Python 3.9+ 的首选接口

Python 3.9 引入了 importlib.resources.files()，取代旧版 open_text()/open_binary() 等函数。它返回一个 Traversable 对象，行为类似 pathlib.Path，支持 .joinpath()、.read_text()、.is_file() 等方法，且天然兼容 zip 包和源码目录。

使用场景：读取配置模板、嵌入 JSON Schema、加载字体/图标等二进制资源。

from importlib import resources
假设包结构为 mypackage/ (含 data/schema.json 和 templates/report.j2)
with resources.files("mypackage").joinpath("data/schema.json").open("r") as f:
schema = json.load(f)
读取二进制资源（如图标）
icon_bytes = resources.files("mypackage").joinpath("assets/icon.png").read_bytes()

• files() 必须传入**包名字符串**（如 "mypackage"），不能是模块对象或相对导入路径
• 若包未安装（仅在开发目录下），需确保当前工作目录包含该包，或通过 -m pip install -e . 安装为可编辑模式
• 不支持跨包访问；files("otherpkg").joinpath("x.txt") 会抛 ModuleNotFoundError，除非 otherpkg 已安装且可导入

处理子包和嵌套资源的路径写法

资源路径中的 / 表示层级分隔，不是操作系统路径分隔符。例如 subpkg/config.yaml 对应 mypackage/subpkg/config.yaml，无论该子包是否被声明为独立包（即有无 __init__.py）。

Python 3.14.3

微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。

容易踩的坑：resources.files("mypackage.subpkg") 会失败，除非 mypackage.subpkg 是一个可导入的子包（含 __init__.py）；否则应统一从顶层包出发，用 joinpath("subpkg/config.yaml")。

• 路径中禁止出现 .. 或以 . 开头；joinpath("../bad.txt") 抛 ValueError
• 空目录不会被识别为资源；joinpath("empty_dir/") 会返回 None 或引发 FileNotFoundError
• 区分大小写：Windows 上可能忽略，但 Linux/macOS 和 zip 包严格区分，"Data" ≠ "data"

兼容旧版 Python 的回退方案

如果代码需同时支持 Python 3.8 及以下，不能直接用 files()。此时应使用 importlib_resources 第三方 backport 包（注意名字带下划线），并在运行时做版本判断。

try:
    from importlib import resources
    if not hasattr(resources, "files"):
        raise ImportError
except ImportError:
    import importlib_resources as resources  # pip install importlib-resources
后续统一用 resources.files(...)

性能影响：backport 版本在 Python 3.9+ 下会自动委托给标准库，几乎无开销；但在 Python 3.7 下，其 files() 实现基于 __file__ 推导，无法支持 zipimport，这点必须在测试中覆盖。

真正容易被忽略的是：资源文件的编码。默认 .read_text() 使用 UTF-8，若资源含 BOM 或 GBK 编码，需显式传 encoding="gbk"；而 .read_bytes() 总是安全的，建议优先用于二进制或需自行解码的文本。