jumphp2installer：为你的软件打造安装程序

jumphp2installer 为 Windows、macOS 和 Linux 生成真正的原生安装程序，可用于你的游戏、JumPHP 应用或任何软件。你只需写一个简短、易读的 YAML 脚本，用户下载一个文件即可。它会显示安装向导（欢迎、许可协议、文件夹、选项），始终安装最新版本，并附带卸载程序。它是自由的开源软件： github.com/davidnurdin/jumphp2installer。

在工作室中创建安装程序下载 jumphp2installer

它能做什么

每个系统一个文件：My-App-setup.exe（Windows 10 和 11）、My-App-setup-macos.zip（Apple 芯片和 Intel 的 Mac）、My-App-setup-linux-x86_64。无需预先安装任何东西。
始终是最新版本：安装程序在启动时读取你的脚本。因此一年前下载的安装程序也会安装今天的版本。
你的配色的向导：你的名称、图标、侧边图片、颜色、许可协议和文字。根据电脑的语言显示英文或法文。
常用步骤：下载（带 SHA-256 校验）、解压（.zip、.tar.gz）、复制、写入文件、设为可执行、运行命令、创建快捷方式（桌面、菜单）。
真正的卸载程序：它出现在 Windows 的“应用”列表和 Linux 的菜单中。它只删除安装时创建的内容，不碰其他东西。
无需管理员权限：一切都为当前用户安装，放在用户自己的程序文件夹中。
也可用命令行：--silent 无窗口安装（部署、脚本、CI）。

安装脚本

install.yaml 文件说明安装程序显示什么（pages）和做什么（steps）。同一个脚本可在三个系统上使用：变量（{folder}、{platform}、{exe}…）和 os: 键负责处理差异。

app:
  name: My App
  publisher: Me
  website: https://example.cn
  icon: icon.png
  banner: banner.png          # 向导左侧的图片（172 x 420）
  accent: "#2f6fed"

version:
  github: me/my-app           # GitHub 的最新发布给出 {version}

pages:
  - welcome
  - license: LICENSE.txt
  - folder: "{programs}/{app}"
  - options:
      desktop: 桌面快捷方式
  - install
  - finish: {run: "{folder}/my-app{exe}"}

steps:
  - download: https://github.com/me/my-app/releases/download/v{version}/my-app-{platform}.zip
  - extract: {strip: 1}
  - executable: "{folder}/my-app"
    os: [linux, macos]
  - shortcut: {target: "{folder}/my-app{exe}", where: desktop}
    if: desktop
  - uninstaller

页面

页面	显示内容
`welcome`	欢迎文字（默认：“欢迎安装 {app} {version}”）
`license`	包中的一个文件，必须接受才能继续
`folder`	文件夹，带“浏览…”、所需空间和可用空间；文件夹已被使用时会提示
`options`	复选框，供步骤再次使用（`if: desktop`）
`install`	进度条和详细信息
`finish`	结束页，带“启动 {app}”复选框（`run`，可按系统不同）

步骤

步骤
`download`	一个地址或包中的文件；文件不对时 `sha256` 会停止一切
`extract`	解压到 `{folder}`；`strip: 1` 去掉压缩包的顶层文件夹
`copy`、`mkdir`、`write`、`delete`	文件和文件夹（`delete` 只作用于安装文件夹、用户文件夹和临时文件夹）
`executable`	使文件可执行（Linux、macOS）
`shortcut`	`desktop`、`menu` 或 `both`：Windows 上为 `.lnk`，Linux 上为 `.desktop`，macOS 上为链接
`run`	在文件夹中运行命令
`uninstaller`	安装卸载程序并在系统中注册

每个步骤都接受 if:（已勾选的选项，或 "!option"）、os:（windows、macos、linux）和 label:。

版本

写法	`{version}`
`version: 1.4.0`	固定
`version: {github: me/my-app}`	仓库的最新发布（其标签，去掉 `v`）
`version: {latest: https://…/latest.json}`	该地址的应答：`{"version": "1.4.0"}` 或纯文本

变量

变量	Windows	Linux	macOS
`{programs}`	`%LOCALAPPDATA%\Programs`	`~/.local/opt`	`~/Applications`
`{desktop}`、`{menu}`	桌面、开始菜单	桌面、`~/.local/share/applications`	`~/Desktop`
`{platform}`	`windows-x86_64`	`linux-x86_64`	`macos-arm64` / `macos-x86_64`
`{exe}`	`.exe`	（空）	（空）
`{folder}`、`{app}`、`{version}`、`{home}`、`{temp}`、`{os}`、`{arch}`、`{download}`

完整参考见 docs/installer/script.md。

三种发布方式

1. 在 jumphp.net 上，无需安装任何东西

在工作室中，“新建安装程序”会打开一个编辑器：

YAML 脚本会在你输入时检查（每个错误都标出行号）；
旁边的向导预览会实时更新；
你可以拖入图片、许可协议和包中的小文件。

发布后，安装程序会获得自己的下载页面和三个链接，每个系统一个。在发布之前，只有你可以试用。

2. 在 GitHub 发布中，无需服务器

包（install.yaml 及其文件）和安装程序会附加到你仓库的每个发布中。安装程序读取最新发布，因此版本之间无需修改任何东西。工作流会在每次发布时完成这些：

# .github/workflows/installer.yml
on:
  release:
    types: [published]
jobs:
  installer:
    uses: davidnurdin/jumphp2installer/.github/workflows/package.yml@main
    with:
      folder: installer        # install.yaml 及其文件
    permissions:
      contents: write

也可以从 jumphp2installer 的克隆中手动完成： tools/github-release.sh me/my-app installer。你的链接： https://github.com/me/my-app/releases/latest/download/My-App-setup.exe。

如果你的仓库发布多个产品（一个用 v* 标签，另一个用 ide-v*），“最新发布”可能属于另一个产品。这时请从仓库的文件提供包（https://raw.githubusercontent.com/…/installer/），旁边放一个 version.json。JumPHP IDE 就是这样做的。

3. 在你自己的服务器上

jumphp2installer 的服务器是一个运行在 Docker 中的 Symfony + MariaDB 应用（仓库中的 server/）：账户、编辑器、预览、下载页面和统计。一条 docker compose up -d 即可启动。简单的静态网页也可以充当服务器（一个包含 install.yaml 及其文件的文件夹）：

php tools/package-release.php my-package/ https://my-site.cn/installer/ bases/ out/

用于 JumPHP 游戏或应用

bin/jumphp app:export my-app --windows --macos（游戏用 export:standalone）会为每个系统生成一个可执行文件。把它们附加到发布中，然后使用 jumphp-app.yaml 示例。你的 Claude 也会做：对它说“为我的游戏做一个安装程序”（仓库中有 jumphp2installer skill）。

命令行

My-App-setup-linux-x86_64 --silent --folder=/opt/my-app --no-option=desktop
My-App-setup.exe --silent
"C:\…\My App\uninstall.exe" --uninstall --silent
jumphp2installer-linux-x86_64 --check --script=install.yaml      # 检查脚本
jumphp2installer-linux-x86_64 --script=install.yaml              # 用本地脚本试用向导
jumphp2installer-linux-x86_64 --make=My-App-setup.exe --server=github:me/my-app --from=jumphp2installer-windows-x86_64.exe

工作原理

安装程序本身就是一个 JumPHP 应用：向导是 HTML 页面，工作由 PHP 完成，运行在 StaticPHP 的独立 PHP 上。包的地址被写入可执行文件的内嵌 php.ini，且文件大小不变。因此服务器无需编译任何东西，就能在一瞬间为每个包生成安装程序。下载和解压每一帧推进一点：窗口永远不会卡住。每个版本发布前，GitHub Actions 都会在 Linux、Windows 和两台 Mac（Apple 芯片和 Intel）上真实测试：安装、快捷方式、卸载条目，然后卸载。

限制

安装程序未签名：Windows SmartScreen 和 macOS Gatekeeper 会在首次运行时提示（Mac 上：右键 › 打开）。
仅为当前用户安装（不支持 Program Files、服务或文件关联）。
不支持 Linux ARM 和手机。
在 Windows 上请通过长路径启动，不要使用 8.3 短文件名（C:\Users\RUNNER~1\…）。