安装与首次使用

本页说明 ArkPets 的分发形态（exe 安装包 / zip 便携版 / jar 版）、Windows 安装器的实际行为（文件落地、PATH 环境变量注册表写入、快捷方式与卸载清理），以及首次运行时程序在工作目录生成的运行时文件。所有内容均来自仓库内真实的构建与安装源码。

Purpose and Scope

本页覆盖以下内容：

ArkPets 的三种分发格式及其差异（exe 安装版、zip 便携版、jar 版）
Windows 安装包 docs/scripts/ExePacking.iss（Inno Setup 6 脚本）的完整解构：安装元数据、多语言支持、文件拷贝、图标创建、PATH 环境变量写入与卸载清理
首次运行时生成的配置与数据文件（ArkPetsConfig.json、models_data.json、logs/、temp/、models*/ 等）
jpackage/jlink 打包链路中与"可运行产物"相关的构建配置

以下主题有意留给兄弟页面，本页不展开：

命令行参数详解 → 参见仓库文档 CmdLine.md
启动器设置界面与自启动服务细节 → 参见 desktop/src/cn/harryh/arkpets/controllers/SettingsModule.java
自定义模型导入 → 参见 CustomModel.md
崩溃日志与调试 → 参见 Debug.md
遥测（Analytics）行为 → 参见 Telemetry.md

Overview

ArkPets 是一款基于《明日方舟》Spine 角色模型的桌面宠物应用。它在仓库中以 Gradle 多模块 Java 项目形式组织（desktop 模块为主体），通过 jlink/jpackage 裁剪出附带精简 JRE 的自包含程序目录，再由 Inno Setup 脚本二次封装为 Windows 安装包。

用户可以选择三种方式获得程序：

分发格式	形态	特点
exe 安装版	`ArkPets-v3.13.1-Setup.exe`	Inno Setup 向导式安装，写入开始菜单/桌面快捷方式，将 `{app}\app` 追加进系统 PATH，支持配置开机自启动
zip 便携版	解压即用的程序目录	无安装器，工作目录即程序目录，同样支持自启动配置
jar 版	单个 `.jar` 文件	需要 Java 运行环境，命令行形如 `java -jar ArkPets.jar`；不支持自启动配置

三种格式的差异在启动器源码中有明确提示——SettingsModule 在无法确认目标程序位置时提示用户："为确保自启动服务的稳定性，直接打开的ArkPets的".jar"版启动器，是不支持配置自启动的。请使用exe版的安装包安装ArkPets后运行，或使用zip版的压缩包解压程序文件后运行。另外，当您使用错误的工作目录运行启动器时也可能出现此情况。"

Source: SettingsModule.java

之所以这样设计：自启动快捷方式/脚本需要指向稳定的绝对路径，而 jar 版由用户通过任意 Java 命令启动，程序无法可靠定位自身落盘位置；exe/zip 版则拥有确定的工作目录结构，因此可安全写入启动项。

Architecture

构建与分发管线

Loading diagram...

各环节说明：

jlink 裁剪：desktop/build.gradle 通过 jlinkModuleList 限定 Java 模块集合（java.base,java.desktop,java.logging,java.management,java.scripting,jdk.crypto.ec,jdk.localedata,jdk.management,jdk.unsupported）并限制 locale 为 en-US,zh-CN，使分发包无需用户预装 JRE。 Source: build.gradle
Inno Setup 封装：ExePacking.iss 把 desktop/build/jpackage/ArkPets/* 整目录拷贝到 {app}，输出文件名为 ArkPets-v{版本}-Setup 到 ..\..\desktop\build\dist。
运行期自描述：首次运行后，程序在安装目录生成配置与数据文件；卸载时这些文件由 [UninstallDelete] 逐一清理（见下文）。

安装器安装/卸载生命周期

Loading diagram...

Main Content

1. 分发格式与自启动约束

ArkPets 的 jpackage 产物是"程序目录"形态（含精简 JRE 的 app 子目录与 ArkPets.exe 启动器），zip 版即直接分发该目录，exe 版由 Inno Setup 封装。jar 版则跳过 jpackage，仅分发可执行 jar。

三种格式的能力差异（依据安装脚本与启动器源码）：

能力	exe 安装版	zip 便携版	jar 版
无需预装 Java	✅	✅	❌（需 `java -jar`）
开机自启动配置	✅	✅	❌
PATH 环境变量注入	✅（安装器写入）	❌	❌
卸载时清理运行时数据	✅（`[UninstallDelete]`）	手动删除	手动删除

jar 版命令行形态在官方文档中明确：命令行应以 java -jar ArkPets.jar 或 ArkPets.jar 开头，注意写完整文件名。 Source: CmdLine.md

2. 安装脚本解构：ExePacking.iss

安装包基于 Inno Setup 6。以下为脚本中的关键元数据定义：

ini

#define MyAppName "ArkPets"
#define MyAppVersion "3.13.1"
#define MyAppPublisher "Harry Huang"
#define MyAppURL "https://arkpets.harryh.cn/"

Source: ExePacking.iss

[Setup] 段决定了安装行为的关键属性：

ini

AppCopyright        = Copyright (C) 2022-2026 {#MyAppPublisher}
AppId               ={{213DB689-8F8A-4DEA-BE79-545FAD7769A6}
AllowNoIcons        =yes
Compression         =lzma2/max
DefaultDirName      ="{userpf}\{#MyAppName}"
PrivilegesRequired  =lowest
OutputBaseFilename  ={#MyAppName}-v{#MyAppVersion}-Setup
OutputDir           =..\..\desktop\build\dist
SetupIconFile       =..\..\..\assets\icons\icon.ico
SolidCompression    =yes
UninstallDisplayIcon={app}\{#MyAppName}.ico
WizardStyle         =modern
ChangesEnvironment  =true

Source: ExePacking.iss

设计意图解读：

PrivilegesRequired = lowest + DefaultDirName = {userpf}：安装到用户级 Program Files 目录（不需要管理员权限），降低安装门槛，同时避免 HKLM 写入需要提权——但注意下文 EnvAddPath 仍写入 HKEY_LOCAL_MACHINE，在 Windows 上 lowest 权限下该写入可能失败并仅记录日志，这是脚本有意保留的行为（失败时 Log(... 'Error while adding ...')）。
ChangesEnvironment = true：告知 Windows 安装后广播 WM_SETTINGCHANGE，使 PATH 变更立即对新进程可见。
Compression = lzma2/max + SolidCompression：以安装耗时换取最小分发包体积。
AppId 为固定 GUID {213DB689-8F8A-4DEA-BE79-545FAD7769A6}，保证升级安装能覆盖同一应用条目。

多语言安装界面通过 [Languages] 段配置，仓库自带简体/繁体中文翻译文件：

ini

[Languages]
Name: "chinese_simplified";  MessagesFile: "ChineseSimplified.isl"
Name: "chinese_traditional"; MessagesFile: "ChineseTraditional.isl"
Name: "english"; MessagesFile: "compiler:Default.isl"
Name: "japanese"; MessagesFile: "compiler:Languages\Japanese.isl"

Source: ExePacking.iss

3. PATH 环境变量写入（核心自定义逻辑）

安装脚本用 Pascal 脚本在安装后把 {app}\app 追加到系统 PATH，卸载时移除：

pascal

const EnvironmentKey = 'SYSTEM\CurrentControlSet\Control\Session Manager\Environment';

procedure EnvAddPath(Path: string);
var
    Paths: string;
begin
    { Retrieve current path (use empty string if entry not exists) }
    if not RegQueryStringValue(HKEY_LOCAL_MACHINE, EnvironmentKey, 'Path', Paths)
    then Paths := '';

    { Skip if string already found in path }
    if Pos(';' + Uppercase(Path) + ';', ';' + Uppercase(Paths) + ';') > 0 then exit;

    { App string to the end of the path variable }
    Paths := Paths + ';'+ Path +';';

    { Overwrite (or create if missing) path environment variable }
    if RegWriteStringValue(HKEY_LOCAL_MACHINE, EnvironmentKey, 'Path', Paths)
    then Log(Format('The [%s] added to PATH: [%s]', [Path, Paths]))
    else Log(Format('Error while adding the [%s] to PATH: [%s]', [Path, Paths]));
end;

Source: ExePacking.iss

实现要点：

幂等性：通过 Pos(';' + Uppercase(Path) + ';', ...) 做大小写不敏感的存在性检查，重复安装不会产生重复条目。
注册表位置：HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment 是系统级 PATH 的权威位置（非 HKCU）。
日志兜底：写入失败不中断安装，仅记录日志，避免用户在没有管理员权限时安装失败。

生命周期钩子将上述过程挂接到位：

pascal

procedure CurStepChanged(CurStep: TSetupStep);
begin
    if CurStep = ssPostInstall
    then EnvAddPath(ExpandConstant('{app}') + '\app');
end;

procedure CurUninstallStepChanged(CurUninstallStep: TUninstallStep);
begin
    if CurUninstallStep = usPostUninstall
    then EnvRemovePath(ExpandConstant('{app}') + '\app');
end;

Source: ExePacking.iss

4. 文件落地、图标与升级清理

ini

[Files]
Source: "..\..\desktop\build\jpackage\{#MyAppName}\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
Source: "..\..\desktop\build\jpackage\LICENSE"; DestDir: "{app}"; Flags: ignoreversion

[Icons]
Name: "{group}\{#MyAppName}"; Filename: "{app}\{#MyAppName}.exe"; WorkingDir: "{app}"
Name: "{group}\{cm:ProgramOnTheWeb,{#MyAppName}}"; Filename: "{#MyAppURL}"
Name: "{group}\{cm:UninstallProgram,{#MyAppName}}"; Filename: "{uninstallexe}"
Name: "{autodesktop}\{#MyAppName}"; Filename: "{app}\{#MyAppName}.exe"; Tasks: desktopicon; WorkingDir: "{app}"

[Run]
Filename: "{app}\{#MyAppName}.exe"; Description: "{cm:LaunchProgram,{#StringChange(MyAppName, '&', '&&')}}"; Flags: nowait postinstall

[InstallDelete]
Type: files; Name: "{app}\app\desktop*.jar"

Source: ExePacking.iss

值得注意的设计：

WorkingDir: {app}：所有快捷方式都显式指定工作目录为安装目录。这非常重要——ArkPets 是以工作目录（working directory）解析配置与模型资源的，SettingsModule 中的提示明确指出"当您使用错误的工作目录运行启动器时也可能出现此情况"。快捷方式固定 WorkingDir 从根上避免了配置错位。
[InstallDelete] 清理 {app}\app\desktop*.jar：升级安装时删除旧版本主 jar，防止 jpackage 目录里残留新旧并存。
postinstall 运行：向导结束后勾选即可直接启动程序，完成"安装即首用"的体验闭环。

5. 首次运行生成的文件与卸载清理

首次运行后，程序在安装目录（工作目录）产生以下文件，它们都被 [UninstallDelete] 覆盖，保证干净卸载：

ini

[UninstallDelete]
Type: files; Name: "{app}\ArkPetsConfig.json"
Type: files; Name: "{app}\models_data.json"
Type: files; Name: "{app}\hs_err_pid*.log"
Type: filesandordirs; Name: "{app}\logs"
Type: filesandordirs; Name: "{app}\temp"
Type: filesandordirs; Name: "{app}\models"
Type: filesandordirs; Name: "{app}\models_enemies"
Type: filesandordirs; Name: "{app}\models_illust"
Type: files; Name: "{userstartup}\ArkPetsStartup.lnk"
Type: files; Name: "{userstartup}\ArkPetsStartupService.vbs"

Source: ExePacking.iss

从这份清单可以反推出首次运行后的目录结构：

文件/目录	作用
`ArkPetsConfig.json`	主配置文件（含 Java 启动参数，可加 `-Darkpets.*` 系统属性）
`models_data.json`	模型元数据索引
`hs_err_pid*.log`	JVM 致命错误转储
`logs/`	应用日志目录
`temp/`	运行时临时文件
`models/` `models_enemies/` `models_illust/`	模型资源目录（本体 / 对战敌人 / 立绘）
`{userstartup}\ArkPetsStartup.lnk` / `ArkPetsStartupService.vbs`	用户"启动"文件夹中的自启动快捷方式与服务脚本

配置文件中追加 Java 选项的官方做法（来自 FAQ）：用记事本打开 ArkPets.cfg，在最后一行添加 java-options=-Darkpets.usesystemfont=true，保存后重启桌宠。 Source: FAQ.md

Failure Modes, Edge Cases & Concurrency

PATH 写入失败不阻断安装：EnvAddPath 写 HKLM 需要管理员权限，而安装器 PrivilegesRequired = lowest；脚本选择失败仅记日志。低权限安装后，{app}\app 可能未进入 PATH——命令行调用能力受影响，但 GUI 启动不受影响。
重复安装幂等：PATH 追加前做大小写不敏感去重，避免升级后出现重复条目。
错误工作目录：若用户从其它目录直接执行 jar（未固定 WorkingDir），程序无法定位自身配置/资源，SettingsModule 会弹窗解释成因。exe 快捷方式通过 WorkingDir: {app} 规避此问题。
升级残留：[InstallDelete] 删除旧 desktop*.jar，防止新旧主程序并存导致启动旧版本。
自启动与格式绑定：jar 版因无法确认程序位置而不支持自启动；卸载时无论用户是否启用自启动，[UninstallDelete] 都会尝试删除启动文件夹中的 ArkPetsStartup.lnk 与 ArkPetsStartupService.vbs，操作本身是安全的（目标不存在时跳过）。

Performance / Operational Notes

分发包体积优化：jlink 裁剪至 8 个 Java 模块 + 2 个 locale（en-US,zh-CN），显著缩小附带 JRE 的体积；Inno Setup 再用 lzma2/max + SolidCompression 压缩。代价是安装解压耗时增加，属于"下载小、安装慢"的取舍。 Source: build.gradle
运维提示：升级即重新运行新版本 Setup.exe（同一 AppId 覆盖安装）；卸载会连模型目录一起删除，备份自定义模型请在卸载前进行（自定义模型导入参见 CustomModel.md）。

Configuration Options

安装器/运行环境相关的可配置项：

项	类型	默认值	说明
`DefaultDirName`	目录	`{userpf}\ArkPets`	安装目标目录（用户级，无需管理员）
`desktopicon` task	布尔	未勾选	是否创建桌面快捷方式（`AllowNoIcons=yes`）
PATH 注入路径	注册表	`{app}\app`	安装后追加到 HKLM 系统 PATH
`java-options` (ArkPets.cfg)	字符串	—	传给 JVM 的参数，如 `-Darkpets.usesystemfont=true`

安装与首次使用

Purpose and Scope

Overview

Architecture

构建与分发管线

安装器安装/卸载生命周期

Main Content

1. 分发格式与自启动约束

2. 安装脚本解构：ExePacking.iss

3. PATH 环境变量写入（核心自定义逻辑）

4. 文件落地、图标与升级清理

5. 首次运行生成的文件与卸载清理

Failure Modes, Edge Cases & Concurrency

Performance / Operational Notes

Configuration Options

Related Links

Sources