JadeView

应用打包

将 JadeUI Python 应用打包为可分发产物时，通常分为两步：

  1. 前端资源：明文 JAPK（开发）或 JadePack 签名包（生产）
  2. Python 宿主：jadeui build 打成独立 .exe（默认 Nuitka，可选 PyInstaller）

CLI 总览与项目约定见 CLI 工具。

前端资源（JAPK）

Shell
# 需已安装 Node.js，并执行: npm install -g @electron/asar
jadeui japk
jadeui japk --src web -o dist/my-app.japk

运行时加载示例：

Python
from jadeui import Window

Window(title="My App").run(japk="dist/my-app.japk")

或通过 LocalServer：

Python
from jadeui import LocalServer

server = LocalServer()
url = server.start("myapp", japk="dist/my-app.japk")

宿主 exe（jadeui build）

打包器（自动安装）

jadeui build 默认会自动安装缺失的打包器，无需再手动装 GitHub 上的 Nuitka rc 包：

  • 默认 Nuitka：自动安装 nuitka>=4.0（PyPI 正式版；勿再使用已过时的 4.0rc7 zip）
  • --packager pyinstaller：自动 pip install pyinstaller

离线或不希望改动环境时可用 --no-auto-deps 关闭。

也可手动预装：

Shell
pip install "nuitka>=4.0"
# 或
pip install jadeui[pyinstaller]

编译环境（MSVC / clang 等）可配合：

Shell
pip install jadeui[dev]
jadeui doctor

基本用法

Shell
jadeui build
jadeui build app.py
jadeui build app.py -o MyApp
jadeui build --packager pyinstaller
jadeui build -i app.ico -o MyApp --output-dir dist
jadeui build --include-data-dir assets=assets --console
jadeui build --no-onefile -c 2

默认行为：

  • 单文件模式（onefile）
  • 压缩级别 1（基础 LTO）
  • 自动包含 JadeView DLL（按当前 Python 架构匹配 x86 / x64 / arm64）
  • 若存在同级 web/ 目录则自动包含
  • 若存在 web/favicon.png 则自动用作图标
  • 未指定 -o 时，输出名跟随 pyproject.toml（见 CLI 项目约定）

命令行参数

参数说明
sourcePython 入口（默认 tool.jadeui.entry 或 app.py）
--packagernuitka（默认）或 pyinstaller
-i, --icon图标（.ico / .png）
-o, --output输出可执行文件名（不含扩展名）
--output-dir输出目录（默认 dist）
--include-data-dir数据目录，源=目标（可多次）
--include-data-file数据文件，源=目标（可多次）
--console显示控制台窗口
--upx启用 UPX（Nuitka）
--no-jadeui-dll不自动包含 JadeView DLL
-c, --compressNuitka 压缩级别 0-3（默认 1）
--no-onefile打包为目录而非单文件
--no-auto-deps禁止自动安装缺失的 Nuitka / PyInstaller

压缩级别（Nuitka）

级别说明编译速度文件大小
0不额外压缩最快最大
1基础优化（LTO）较快较大
2LTO + 移除 docstring / assert较慢较小
3全部优化 + Python -OO最慢最小

推荐日常使用 -c 2。

推荐项目结构

Markdown
my_app/
├── app.py
├── pyproject.toml      # [project] + [tool.jadeui]
├── web/                # 前端（自动包含 / japk 源）
│   ├── index.html
│   └── favicon.png
└── assets/             # 其它资源（需 --include-data-dir）

完整示例

Shell
jadeui init my-app --frontend html
cd my-app
jadeui doctor
jadeui run
jadeui japk
jadeui build -o MyApp -c 2

输出示例：

Markdown
dist/
├── my-app.japk    # 前端资源（若执行了 japk）
└── MyApp.exe      # 宿主可执行文件

兼容旧脚本

仓库内旧入口 scripts/build.py 仍会转发到同一套打包实现，新项目请直接使用 jadeui build。

常见问题

Q: 打包后提示缺少 DLL / VC++ 运行时？

A: 使用 Nuitka >=4.0（pip install "nuitka>=4.0"）；并确认产物中的 JadeView DLL 与打包时使用的 Python 架构一致（不要用「系统是 64 位」代替「解释器是 64 位」）。

Q: SDK 会自动升到最新 JadeView 吗？

A: 只会在已适配的 release tag 内选择最新 build（例如 v2.3.0 下的 26G02 → 同 tag 后续修订）。不会自动跨到 2.4。

Q: 如何减小体积？

A: 提高 -c、可选 --upx、去掉不必要的数据目录；必要时使用较低版本 Python。

Q: web 目录没有被自动包含？

A: 确保 web 与入口脚本同级；否则用 --include-data-dir 指定。

Q: 如何调试打包后的程序？

A:

Shell
jadeui build app.py --console

并在开发阶段启用 DevTools / 右键菜单：

Python
app.initialize(enable_dev_tools=True)
window = Window(disable_right_click=False, ...)

参考链接

Previous
CLI 工具
Next
API 参考