从零定制与构建 CopyQ Windows 安装包:Inno Setup 脚本全解析

原创2026-09-22 17:25:092,153 阅读
文章标签:桌面应用插件系统CLI国际化

从零定制与构建 CopyQ Windows 安装包:Inno Setup 脚本全解析

CopyQ 的 Windows 安装程序(copyq-<版本>-setup.exe)并非由手写代码生成,而是由 Inno Setup 根据仓库中的 shared/copyq.iss 脚本脚本化打包产出。本文以 docs/customize-and-build-the-windows-installer.rst 为骨架,结合仓库内完整的 .iss 脚本、发布脚本与目录结构,讲解如何为安装包添加多语言翻译、在本地修改并试编译安装包,以及脚本各段([Setup]、[Languages]、[Components]、[Files]、[Icons]、[Run] 等)的具体含义。读完后,你将能够脱离 CI,仅凭便携版目录 + 仓库克隆 + Inno Setup 三样东西,独立定制并构建属于自己的 CopyQ Windows 安装包。

一、安装包是从哪里来的:一条从 CI 到 setup.exe 的流水线

正常情况下,CopyQ 的 Windows 安装文件由 CI 自动生成:先由构建流水线从编译产物整理出一个“便携版应用目录”(portable app folder),再调用 Inno Setup 编译器,把该目录里的可执行文件、插件 DLL、翻译文件、主题和 Qt 运行时打包成单个 setup.exe。

这条流水线的产物在发布流程中有明确约定:

  • RELEASE.md 将 copyq-VERSION-setup.exe 列为 Windows 安装包工件,与 copyq-VERSION.zip(Windows 便携版)、macOS DMG、Linux AppImage 并列;
  • utils/github/draft-release.sh 在 expected_assets 中显式校验 "copyq-${version}-setup.exe" 与 "copyq-${version}.zip" 必须由 CI 产出后才能打开发布草稿;
  • utils/fosshub.py 在发布上传时把 copyq-{version}-setup.exe 标注为 “Windows Installer”、copyq-{version}.zip 标注为 “Windows Portable”。

换句话说,便携版 zip 与安装包之间存在直接对应关系:安装包的本质,就是“便携版目录 + Inno Setup 脚本”经过编译后的封装。理解这一点,是本地定制安装包的前提——你不需要重新编译 CopyQ 本体,只需拿到解压后的便携版即可。

二、认识安装包脚本:shared/copyq.iss 的整体结构

安装包的全部逻辑集中在一个文件 shared/copyq.iss(约 200 行)中。它遵循 Inno Setup 的标准分节格式,从头到尾依次是:

节(Section) 作用
文件头注释 + #define 预处理指令 定义应用名、版本、版权、路径等宏;支持通过环境变量 COPYQ_INNO_SETUP 注入(见第五节)
[Setup] 安装程序的全局元数据:AppId、版本、默认安装目录、架构限制、压缩方式、卸载信息等
[Languages] 声明安装向导支持的语言,每种语言引用 Inno Setup 自带的 MessagesFile
[CustomMessages] CopyQ 特有的界面文案翻译(各语言前缀区分)
[Types] / [Components] 定义“完整 / 紧凑 / 自定义”三种安装类型及可勾选的组件树
[Tasks] 安装时可选的额外任务:桌面图标、开机自启
[Files] 将便携版目录中的文件按组件分发到安装目录
[Icons] 创建开始菜单、桌面、启动文件夹中的快捷方式
[Run] 安装结束后(可选)立即启动 CopyQ
[Code] Pascal 脚本,用于把“完整/紧凑/自定义”映射到 Inno Setup 内置消息

文件的头部注释给出了使用前提,这也是整套脚本的唯一硬性要求:

  • 使用**支持 Unicode 且带预处理器(preprocessor)**的 Inno Setup 版本打开;
  • 修改文件开头的 #define(或借助 COPYQ_INNO_SETUP 环境变量);
  • 编译生成 setup.exe。

下文第三节将给出原文推荐的最小改法,第四、五节则深入各分节的实现细节。

三、为安装程序添加翻译:从 en. 复制到 de.

安装向导中绝大多数文案(“下一步”“完成”“安装目录”等)直接取自 Inno Setup 自带的语言文件(对应 [Languages] 节中 compiler:Default.isl、compiler:Languages\German.isl 等),无需 CopyQ 自己维护。仓库只需要补充 CopyQ 特有的消息——例如各插件在组件选择页里的显示名、默认安装目录名“Program Files”等。

这些消息集中在 shared/copyq.iss 的 [CustomMessages] 节,以“语言前缀.键名”的形式组织:

en.ProgramFiles=Program Files
en.Translations=Translations
en.Plugins=Plugins
en.PluginText=Text with Highlighting
en.PluginImages=Images
en.PluginWeb=Web Pages
en.PluginNotes=Notes
en.PluginEncrypted=Encryption
en.PluginFakeVim=FakeVim Editor
en.PluginSynchronize=Synchronize Items to Disk
en.PluginTags=Item Tags
en.PluginPinned=Pinned Items

添加一种新语言翻译的官方做法:从 [CustomMessages] 中复制以 en. 开头的行,把前缀改为目标语言的两位代码即可。例如要为德语翻译,复制 en. 行并把前缀改为 de.:

de.ProgramFiles=Programme
de.Translations=Übersetzungen
de.Plugins=Plugins
de.PluginText=Text mit Hervorhebung
de.PluginImages=Bilder
de.PluginWeb=Webseiten
de.PluginNotes=Notizen
de.PluginEncrypted=Verschlüsselung
de.PluginFakeVim=FakeVim-Editor
de.PluginSynchronize=Elemente auf Datenträger synchronisieren
de.PluginTags=Element-Tags
de.PluginPinned=Angeheftete Elemente

仓库当前内置了 6 种语言,分别是 en(英语)、cz(捷克语)、de(德语)、es(西班牙语)、it(意大利语)、ko(韩语)。注意两点:

  1. [Languages] 节必须同时声明该语言及其 MessagesFile(指向 Inno Setup 自带语言包),[CustomMessages] 中的前缀才会生效;
  2. 翻译不必逐条齐全。从源码可见,de. 前缀只定义了 AutoStartProgram 一条(对应 [Tasks] 中“自动启动”任务的文案 {cm:AutoStartProgram,CopyQ}),其余 de. 键缺失时会自动回退到其他语言,这正是“只复制需要覆盖的 en. 行”这一做法的设计原因。

组件名的翻译与 [Components] 节通过 {cm:PluginText} 这类常量引用,例如 Description: "{cm:PluginText}",因此翻译键一旦定义,组件选择页会立即生效。

四、本地修改并测试安装包:三步走

原文给出的本地定制流程非常轻量——不需要重新编译 CopyQ 本体,只需要三样东西:

  1. 下载并解压便携版应用:即官方发布的 copyq-<版本>.zip(Windows Portable),解压后得到一个包含 copyq.exe、plugins、translations、themes 等子目录的完整应用目录;
  2. 克隆本仓库:用于获取 shared/copyq.iss 脚本及其引用的资源文件(许可证、图标);
  3. 安装 Inno Setup:需包含 Unicode 支持与预处理器(这两项在默认安装选项中即可选装)。

随后,用 Inno Setup 打开 shared/copyq.iss,在文件开头追加三行 #define:

#define AppVersion 2.8.1-beta
#define Source C:\path\to\CopyQ-repository-clone
#define Destination C:\path\to\CopyQ-portable

逐行解释:

  • AppVersion:写入安装包属性与安装界面显示的版本号,同时决定输出文件名 copyq-2.8.1-beta-setup.exe(见 [Setup] 中 OutputBaseFilename={#MyAppNameMin}-{#AppVersion}-setup);
  • Source:指向仓库克隆根目录,脚本据此定位许可证文件与图标:LicenseFile={#Source}\shared\gpl-3.0.rtf、SetupIconFile={#Source}\src\images\icon.ico;
  • Destination:指向解压后的便携版目录,是打包内容的来源。

完成这三行定义后,即可在 Inno Setup 中随意修改脚本并点击编译运行,反复验证安装、卸载、组件勾选等行为,实现“改一改、跑一跑”的快速迭代。

仓库现状提示:当前检入的 shared/copyq.iss 中,[Setup] 段使用 {#Source} 引用仓库路径,而 [Files] 段实际引用的是 {#Root}(如 Source: "{#Root}\copyq.exe")。这是 CI 环境与文档示例在宏命名上的历史差异——CI 构建时会把便携版目录注入为 Root。本地按文档示例操作时,若编译报 {#Root} 未定义,请在文件开头补一行 #define Root C:\path\to\CopyQ-portable(与 Destination 指向同一目录)即可,两者语义一致。

完整的最小可编译头部示例

将上述宏与脚本默认定义合并后,文件头部大致如下:

; Path for output installation file
#define Output                   "."
#define MyAppName                "CopyQ"
#define MyAppNameMin             "copyq"
#define MyAppCopyright           "Lukas Holecek"
#define MyAppCopyrightStartYear  "2009"
#define MyAppCopyrightEndYear    GetDateTimeString('yyyy','','')

; --- 本地定制:按需修改 ---
#define AppVersion 2.8.1-beta
#define Source C:\path\to\CopyQ-repository-clone
#define Root C:\path\to\CopyQ-portable
#define Destination C:\path\to\CopyQ-portable

; Default AppVersionNumeric to AppVersion for standalone builds.
#ifndef AppVersionNumeric
#define AppVersionNumeric AppVersion
#endif

五、脚本分节深度拆解

5.1 [Setup]:安装包的全局元数据

AppId={{9DF1F443-EA0B-4C75-A4D3-767A7783228E}
AppName={#MyAppName}
AppVersion={#AppVersion}
AppVerName={#MyAppName} {#AppVersion}
UninstallDisplayName={#MyAppName} {#AppVersion}
UninstallDisplayIcon={app}\copyq.exe
DefaultDirName={autopf}\{#MyAppName}
DefaultGroupName={#MyAppName}
ArchitecturesAllowed=x64
ArchitecturesInstallIn64BitMode=x64
AllowNoIcons=yes
PrivilegesRequiredOverridesAllowed=dialog
OutputBaseFilename={#MyAppNameMin}-{#AppVersion}-setup
Compression=lzma
SolidCompression=yes
SetupIconFile={#Source}\src\images\icon.ico
WizardImageFile=logo.bmp
WizardSmallImageFile=logo-small.bmp
CloseApplications=force

关键点:

  • AppId 是安装包的全局唯一标识(GUID),决定“升级/覆盖安装”时如何识别旧版本,不要随意改动;
  • ArchitecturesAllowed=x64 + ArchitecturesInstallIn64BitMode=x64:安装包仅面向 64 位 Windows,且强制以 64 位模式安装到 Program Files;
  • DefaultDirName={autopf}\CopyQ:默认安装目录为 Program Files\CopyQ;
  • Compression=lzma + SolidCompression=yes:使用 LZMA 算法做实心压缩,体积小但编译耗时较长;
  • CloseApplications=force:安装/卸载前自动强制关闭正在运行的 CopyQ,避免文件占用导致失败;
  • PrivilegesRequiredOverridesAllowed=dialog:允许用户在安装向导中选择“仅为当前用户安装”(无需管理员权限);
  • WizardImageFile / WizardSmallImageFile 引用的 logo.bmp、logo-small.bmp 位于 shared/ 目录。

版本号处理上有一处巧妙设计:#ifndef AppVersionNumeric 使 AppVersionNumeric 默认回退为 AppVersion,供 VersionInfoVersion(要求纯数字版本号)使用;CI 等场景可通过预定义 AppVersionNumeric 覆盖,例如将 2.8.1-beta 转换为 2.8.1。

5.2 [Languages] 与 [CustomMessages]:双语种文案体系

[Languages]
Name: en; MessagesFile: "compiler:Default.isl"
Name: cz; MessagesFile: "compiler:Languages\Czech.isl"
Name: de; MessagesFile: "compiler:Languages\German.isl"
Name: es; MessagesFile: "compiler:Languages\Spanish.isl"
Name: it; MessagesFile: "compiler:Languages\Italian.isl"
Name: ko; MessagesFile: "compiler:Languages\Korean.isl"

[Languages] 决定安装向导可切换的语言集合;[CustomMessages] 则只补充 CopyQ 特有的键(第三节已述)。二者结合,即“官方通用文案交给 Inno Setup,项目特有文案自行维护”的分工。

5.3 [Types] 与 [Components]:安装类型与组件树

[Types]
Name: "full"; Description: "{code:GetFullInstallation}"
Name: "compact"; Description: "{code:GetCompactInstallation}"
Name: "custom"; Description: "{code:GetCustomInstallation}"; Flags: iscustom

三种安装类型:“完整安装”“紧凑安装”“自定义安装”。{code:Get...Installation} 调用文件末尾 [Code] 节中的 Pascal 函数,把类型名映射为 Inno Setup 内置消息 msgFullInstallation / msgCompactInstallation / msgCustomInstallation,从而自动获得多语言显示。

组件树([Components])共 10 个节点,映射关系如下:

组件 含义 所属安装类型
program 主程序文件 full / compact / custom(Flags: fixed,不可取消)
translations Qt 翻译文件(translations\*.qm) full / compact / custom
plugins/text 文本高亮插件(*itemtext.dll) full
plugins/images 图片插件(*itemimage.dll) full
plugins/notes 笔记插件(*itemnotes.dll) full
plugins/encrypted 加密插件(*itemencrypted.dll) full
plugins/fakevim FakeVim 编辑器插件(*itemfakevim.dll) full
plugins/synchronize 磁盘同步插件(*itemsync.dll) full
plugins/tags 条目标签插件(*itemtags.dll) full
plugins/pinned 固定条目插件(*itempinned.dll) full

每个插件组件对应的 DLL 源文件,与仓库 plugins/ 目录下的模块一一对应(itemtext、itemimage、itemnotes、itemencrypted、itemfakevim、itemsync、itemtags、itempinned)。组件选择页上显示的名称,正是第三节 [CustomMessages] 中翻译的 PluginXxx 键。

5.4 [Files]:便携版目录 → 安装目录的打包规则

[Files]
Source: "{#Root}\copyq.exe"; DestDir: "{app}"; Components: program; Flags: ignoreversion
Source: "{#Root}\snoretoast.exe"; DestDir: "{app}"; Components: program; Flags: ignoreversion skipifsourcedoesntexist
Source: "{#Root}\AUTHORS"; DestDir: "{app}"; Components: program; Flags: ignoreversion
Source: "{#Root}\LICENSE"; DestDir: "{app}"; Components: program; Flags: ignoreversion
Source: "{#Root}\README.md"; DestDir: "{app}"; Components: program; Flags: ignoreversion
Source: "{#Root}\themes\*"; DestDir: "{app}\themes"; Components: program; Flags: ignoreversion
Source: "{#Root}\translations\*.qm"; DestDir: "{app}\translations"; Components: translations; Flags: ignoreversion
Source: "{#Root}\plugins\*itemtext.dll"; DestDir: "{app}\plugins"; Components: plugins/text; Flags: ignoreversion
...

打包规则要点:

  • 主程序 copyq.exe、snoretoast.exe(Windows 原生通知程序,缺失时跳过:skipifsourcedoesntexist)、AUTHORS、LICENSE、README.md、themes 目录归属 program 组件,随程序必装;
  • translations\*.qm 只装已编译的 Qt 翻译文件(.qm 而非 .ts 源文件),归属 translations 组件;
  • 各插件 DLL 按名称前缀分别归属对应 plugins/* 组件,实现“紧凑安装不含插件”;
  • 末尾一组 *.dll 通配规则(bearer、imageformats、platforms、styles、tls、crypto 子目录及根目录 DLL)打包 Qt 与工具链运行时,均带 recursesubdirs createallsubdirs 保留子目录结构,归属 program;
  • Flags: ignoreversion 允许覆盖已存在文件而不触发版本检查,是升级安装的关键。

5.5 [Icons] 与 [Run]:快捷方式与安装后动作

[Icons]
Name: "{group}\CopyQ"; Filename: "{app}\copyq.exe"; Parameters: "--start-server show"
Name: "{commondesktop}\CopyQ"; Filename: "{app}\copyq.exe"; Tasks: desktopicon
Name: "{userstartup}\CopyQ"; Filename: "{app}\copyq.exe"; Tasks: startup
  • 开始菜单快捷方式默认创建,启动参数 --start-server show 让 CopyQ 以“启动服务器并显示主窗口”方式运行(对应 clipboardserver 相关命令行模式);
  • 桌面图标与开机自启快捷方式分别受 [Tasks] 中的 desktopicon、startup 任务控制,二者默认均为未勾选(Flags: unchecked),且 startup 任务文案引用 {cm:AutoStartProgram,CopyQ}——这正是第三节中 de.AutoStartProgram=Starte %1 automatisch 发挥作用的位置。

[Run] 段在安装完成后执行:

[Run]
Filename: "{app}\copyq.exe"; Description: "{cm:LaunchProgram,CopyQ}"; Flags: nowait postinstall skipifsilent

即安装结束页提供“运行 CopyQ”勾选项;postinstall 表示放在安装完成之后、skipifsilent 表示静默安装时跳过,nowait 不阻塞安装进程。

5.6 [Code]:Pascal 辅助代码

function GetFullInstallation(Param: string): string;
begin
	Result := SetupMessage(msgFullInstallation);
end;

三个同构函数把组件类型描述转译为 Inno Setup 内置消息,确保“完整/紧凑/自定义”在 6 种语言下都能正确显示。若未来要新增安装类型或改用自定义描述文本,修改这里即可。

六、替代方案:用 COPYQ_INNO_SETUP 环境变量注入配置

除了在文件头部手工添加 #define,shared/copyq.iss 的头部注释还提示了第二种配置方式:通过 COPYQ_INNO_SETUP 环境变量注入参数。这是为 CI 场景设计的——构建脚本无需改动仓库文件,只需在调用 Inno Setup 编译器前设置环境变量,例如:

set COPYQ_INNO_SETUP=AppVersion=2.8.1;Source=C:\repo;Root=C:\portable

配合脚本中已有的 #ifndef 守卫(如 AppVersionNumeric),可在“环境变量/命令行预定义值”与“文件内默认值”之间灵活取舍:外部定义了就用外部的,否则回退到文件内定义。这使得同一个 copyq.iss 既能被 CI 复用,也能被本地开发者直接使用。

七、与发布流水线的衔接

本地定制与 CI 产出遵循同一套脚本,因此验证本地安装包也就等同于验证发布安装包。发布侧的相关约定可作为参照:

  • RELEASE.md 明确发布工件含 Windows 安装包 copyq-VERSION-setup.exe 与便携版 copyq-VERSION.zip;
  • utils/github/draft-release.sh 会等待 Windows CI 完成后下载工件、校验全部资产齐全(含 setup.exe)、生成 SHA-512 校验和并签名,再上传至草稿发布;
  • 发布上传工具 utils/fosshub.py 对 setup.exe 与 .zip 的命名有硬性约定(copyq-{version}-setup.exe),本地定制时若修改了 OutputBaseFilename,需同步考虑发布脚本的期望文件名。

八、常见问题与调试建议

  • 编译报“未定义的宏”:优先检查 #define Source、#define Root 是否都已指向正确路径;[Files] 段引用的是 {#Root}(便携版目录),[Setup] 段的许可证与图标引用的是 {#Source}(仓库目录)。
  • 安装包体积偏大或编译慢:属正常现象——脚本采用 Compression=lzma + SolidCompression=yes 的实心压缩策略,换取更小的产物。
  • 仅支持 64 位系统:ArchitecturesAllowed=x64 与 ArchitecturesInstallIn64BitMode=x64 限制了安装包只在 64 位 Windows 上运行、安装到 64 位 Program Files。若需 32 位支持,需同步调整这两项及 Qt 运行时打包。
  • 覆盖安装失败:确认 CloseApplications=force 生效(安装前强制关闭 CopyQ 进程);同时所有 DLL 均带 ignoreversion 标志,避免版本比较导致旧文件残留。
  • 新语言不显示:检查 [Languages] 是否已声明该语言及对应 MessagesFile,并确认 Inno Setup 安装时包含该语言包;[CustomMessages] 前缀必须与 [Languages] 中的 Name 一致。
  • 每次安装都弹语言选择:[Setup] 中 UsePreviousLanguage=no 关闭了语言记忆,这是刻意为之,若想记住上次选择可将其移除或设为 yes。

至此,从翻译定制、本地试编译到分节原理,CopyQ 的 Windows 安装包构建链路已全部打通。核心要点可归纳为一句话:安装包 = Inno Setup 脚本(shared/copyq.iss)+ 便携版目录 + 三个路径/版本宏,掌握了这三者的组合方式,你就可以像 CI 一样随时产出定制版 copyq-<版本>-setup.exe。

登录后查看全文
CopyQ