20250920 在windwon11使用 PyInstaller 打包 NiceGUI 项目时出现找不到文件

🎯 问题概述

在使用 PyInstaller 打包 NiceGUI 项目时，运行后出现：

1
2


FileNotFoundError: [Errno 2] No such file or directory:
'C:\\Users\\111i|\\AppData\\Local\\Temp\\_NEI107522\\nicegui\\static\\sad_face.svg'

这说明打包后的可执行文件在运行时找不到 NiceGUI 的静态资源（nicegui/static 目录下的 SVG、CSS、JS 等文件）。

NiceGUI 在启动时会把自己的 static 目录复制到临时目录（_NEIxxxxx），如果这些文件没有随可执行文件一起打包，就会导致上述错误。

下面提供 完整的解决方案，包括：

把 NiceGUI 静态资源加入 PyInstaller 打包
在代码中兼容 PyInstaller 的临时路径（sys._MEIPASS）
常见坑 & 调试技巧

📦 1. 把 NiceGUI 静态文件加入打包

1.1 使用 `--add-data` 参数（单行命令）

1
2
3
4


# Windows 示例（分号 ; 作为分隔符）
pyinstaller -F your_app.py \
--add-data "C:\Python311\Lib\site-packages\nicegui\static;nicegui/static" \
--add-data "C:\Python311\Lib\site-packages\nicegui\templates;nicegui/templates"

第一个路径是 NiceGUI 安装目录（根据你的 Python 环境自行修改）。
第二个路径是 目标相对路径，在运行时会解压到 dist/your_app/_MEIPASS/nicegui/static。
同时把 templates（如果你自定义了页面模板）一起加入。

Linux/macOS 使用冒号 : 代替分号，例如 --add-data "/usr/local/lib/python3.11/site-packages/nicegui/static:nicegui/static"

1.2 使用 `.spec` 文件（更灵活）

如果你已经有 .spec 文件，直接在 Analysis 的 datas 参数里添加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


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

block_cipher = None

a = Analysis(
['your_app.py'],
pathex=['.'],
binaries=[],
datas=[
# (源文件/文件夹, 目标相对路径)
('C:\\Python311\\Lib\\site-packages\\nicegui\\static', 'nicegui/static'),
('C:\\Python311\\Lib\\site-packages\\nicegui\\templates', 'nicegui/templates')
],
hiddenimports=[],
hookspath=[],
runtime_hooks=[],
excludes=[],
win_no_prefer_redirects=False,
win_private_assemblies=False,
cipher=block_cipher,
)

# 其余保持不变
...

保存后执行：

1

pyinstaller your_app.spec

🛠️ 2. 代码中兼容 PyInstaller 的临时目录

NiceGUI 在内部会通过 pkg_resources 或 importlib.resources 去读取 static 文件。如果你在代码里自行读取（比如 open('nicegui/static/sad_face.svg')），需要使用下面的 resource_path 函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import sys
import os

def resource_path(relative_path: str) -> str:
"""
在普通运行时返回相对路径；
打包后返回临时解压目录（sys._MEIPASS）中的路径。
"""
if getattr(sys, 'frozen', False):# PyInstaller 打包后
base_path = sys._MEIPASS
else:# 开发时
base_path = os.path.abspath(".")
return os.path.join(base_path, relative_path)

使用示例：

1
2
3
4


svg_path = resource_path('nicegui/static/sad_face.svg')
with open(svg_path, 'r', encoding='utf-8') as f:
svg_content = f.read()
# 这里把 svg_content 交给 NiceGUI 或自行渲染

注意：如果你仅使用 NiceGUI 的 API（ui.button, ui.html 等），通常不需要手动读取这些文件，只要把 static 目录加入打包即可。

🐞 3. 常见坑 & 调试技巧

症状	可能原因	解决办法
运行后报 `FileNotFoundError`，路径指向 `AppData\Local\Temp\_NEIxxxxx\nicegui\static`	`static` 目录未被打包或路径写错	确认 `--add-data` 中的源路径与目标路径正确；重新执行 `pyinstaller --clean`
打包后 UI 正常，但图标/图片缺失	只加入了 `static`，但实际使用的资源在 `templates` 或自定义文件夹	同时把 `templates`、自定义 `assets` 目录加入 `datas`
程序一闪而过（没有任何报错）	使用了 `-w/--windowed`，异常被吞掉	暂时改为 `-c`（控制台）或加 `--debug=all`，在终端查看 traceback
报 `ImportError: cannot import name 'nicegui'`	隐式导入未被检测	在 `Analysis` 中加入 `hiddenimports=['nicegui']`，或在命令行加 `--hidden-import=nicegui`
打包体积非常大	把整个 `site‑packages` 都加入了	只加入 `nicegui/static`、`nicegui/templates`，其余依赖由 PyInstaller 自动收集即可
运行时提示 `DLL load failed`	NiceGUI 依赖的 `uvicorn`、`starlette` 等底层库的 C 扩展未打进	使用 `--collect-all uvicorn`、`--collect-all starlette`（或 `--collect-all nicegui`）

快速定位缺失文件

1
2
3
4


# 在 dist 目录下搜索 nicegui/static
cd dist/_appfind . -type f -name "sad_face.svg"
# Windows PowerShell
Get-ChildItem -Recurse -Filter "sad_face.svg"

如果找不到，说明 --add-data 没起作用，重新检查路径分隔符和目标路径。

📚 4. 完整示例（单文件、窗口模式）

1
2
3
4
5
6


pyinstaller -F -w your_app.py \
--add-data "C:\Python311\Lib\site-packages\nicegui\static;nicegui/static" \
--add-data "C:\Python311\Lib\site-packages\nicegui\templates;nicegui/templates" \
--hidden-import=nicegui \
--collect-all=nicegui \
--icon=app.ico

-F → 单文件 exe
-w → 无控制台（GUI）
--icon → 可选图标
--hidden-import 与 --collect-all 防止隐式导入遗漏

🚀 5. 小结 & 下一步

把 NiceGUI 的 static（以及 templates）目录通过 --add-data 加入打包。
在代码里使用 resource_path() 读取资源，兼容 PyInstaller 的临时路径。
调试时使用控制台模式或 --debug，确保能看到完整的错误信息。
如还有 其他缺失的文件（如自定义图片、配置文件），同样使用 --add-data 并在代码里用 resource_path 读取。

如果你已经尝试了上述步骤但仍报同样的错误，或想要把自定义的 assets/ 目录一起打进去，请把 1️⃣ 完整的打包命令（包括你现在使用的 pyinstaller 参数） 2️⃣ 项目中读取资源的代码片段 发给我，我可以帮你写出精准的 --add-data 参数或 .spec 配置。

祝你打包顺利 🚀！