从零定制与构建 CopyQ Windows 安装包:Inno Setup 脚本全解析
从零定制与构建 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(韩语)。注意两点:
[Languages]节必须同时声明该语言及其MessagesFile(指向 Inno Setup 自带语言包),[CustomMessages]中的前缀才会生效;- 翻译不必逐条齐全。从源码可见,
de.前缀只定义了AutoStartProgram一条(对应[Tasks]中“自动启动”任务的文案{cm:AutoStartProgram,CopyQ}),其余de.键缺失时会自动回退到其他语言,这正是“只复制需要覆盖的en.行”这一做法的设计原因。
组件名的翻译与 [Components] 节通过 {cm:PluginText} 这类常量引用,例如 Description: "{cm:PluginText}",因此翻译键一旦定义,组件选择页会立即生效。
四、本地修改并测试安装包:三步走
原文给出的本地定制流程非常轻量——不需要重新编译 CopyQ 本体,只需要三样东西:
- 下载并解压便携版应用:即官方发布的
copyq-<版本>.zip(Windows Portable),解压后得到一个包含copyq.exe、plugins、translations、themes等子目录的完整应用目录; - 克隆本仓库:用于获取 shared/copyq.iss 脚本及其引用的资源文件(许可证、图标);
- 安装 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。