使用 AAPS Builder 在浏览器中构建

备注

这是使用 Android 手机 构建 AAPS 的推荐方式。它也适用于任何电脑上的浏览器。有关在电脑或 iPhone 上构建的其他方式，请参阅 浏览器构建 概览。

AAPS Builder 会在 GitHub（免费的代码托管网站）上为你构建 AAPS 应用。手机无需安装任何软件，也不需要打开准备文件。

本网站上的设置页面会引导你完成操作。首次大约需要 10 分钟：

1. 在你的 GitHub 帐户中创建一个空的私有仓库：设置页面会打开已填写好的 GitHub 页面，你只需确认即可。

2. 添加构建工作流，也就是告诉 GitHub 如何构建 AAPS 的文件。

3. 创建或上传你的签名密钥（keystore）。

4. 将密钥作为 GitHub secret 提供给你的仓库。

5. 构建应用。每次构建需要 15 到 30 分钟。

6. 下载并安装应用到手机。

你不需要 fork AndroidAPS：每次构建时，AAPS 源代码都会从官方 AndroidAPS 仓库下载。你也不需要 Google Drive：可以直接从 GitHub 下载应用。

代码的来源

设置页面和构建工作流都是本文档的一部分；它们与文档一起维护和审核。你添加到仓库中的 workflow 很短：它会运行文档仓库中维护的 构建步骤，并固定到一个经过审核的版本。你可以在使用前阅读这两者。构建时，该工作流只会下载官方 AAPS 源代码和 GitHub 自己的构建工具。你的 keystore 不会离开浏览器和你的私有仓库。

开始前

你需要：

• 一个免费的 GitHub 帐户。如果还没有，请先在 github.com 创建。

• 一个网页浏览器：手机上的 Chrome，或电脑上的任意浏览器。开始前，请在该浏览器中登录 github.com。

• 手机上的 GitHub 应用？ 可以保留。设置页面中的某些按钮可能会因此在 GitHub 应用中打开，而不是在 Chrome 中打开。在应用中可以完成构建，但应用无法下载完成的 AAPS：第 6 步会说明如何切换到 Chrome 下载。

• 如果你以前构建过 AAPS 并希望在不重新安装的情况下更新，请准备好现有的 keystore（.jks 文件）、其密码和别名。

警告

你的构建仓库必须保持私有。 构建生成的所有内容，任何能看到该仓库的人都可以看到。设置页面会为你创建私有仓库。切勿将其改为公开仓库。

私有仓库每月可获得 2000 分钟免费的 GitHub Actions 使用时间，足够进行多次构建。

警告

新密钥还是现有密钥：这决定了你能否更新 AAPS。

• 手机上已有 AAPS，且仍保留用于构建它的 keystore：在设置页面选择 I already have a keystore 并上传它。下一次构建会原地更新 AAPS。如果你使用以前的浏览器构建方式（自己的 fork）构建过 AAPS，你的 keystore 在 fork 中：先获取一份副本。

• 第一次构建 AAPS，或者丢失了 keystore 或其密码：选择 Create a new key。使用新密钥签名的应用无法更新使用其他密钥签名的 AAPS。你必须导出设置，将文件复制到手机之外，卸载旧版 AAPS，安装新版，然后导入设置：参见 丢失 keystore。

之后始终使用同一个密钥。创建新密钥时，请下载页面提供的备份，并将它与密码和别名（key0）一起安全地存放在手机之外。

从以前的浏览器构建方式（fork）迁移

如果你从未使用以前的浏览器构建方式（在 GitHub 中拥有自己的 AndroidAPS 副本或 fork，并使用准备文件和 Google Drive），请跳过本节。

你的 keystore 以 secret 的形式存储在 fork 中。GitHub 不会再次显示 secret，因此无法将它复制到新仓库。请先获取一份 keystore 副本，然后在第 3 步选择 I already have a keystore 使用它。

警告

不要选择 Create a new key。使用新密钥构建的 AAPS 无法更新手机上的 AAPS。

哪种情况适合你？

• 你使用了选项 2（从 Android Studio 上传了自己的 keystore），并且仍然有 .jks 文件、其密码和别名：这里无需操作。在第 3 步使用该文件。

• 你使用了选项 1（准备文件创建了密钥），或者不再拥有 keystore 文件：按下面的步骤从 fork 导出它。

从 fork 导出 keystore：

1. 在 fork 中打开 Settings → Secrets and variables → Actions，然后添加名为 ZIP_PASSWORD 的 secret。密码只能使用英文字母和数字。它用于保护即将创建的文件。

2. 打开 fork 的 Actions 选项卡，点击 CI Keystore Export，然后点击 Run workflow。更多详情请参见：导出 keystore。

3. 运行显示绿色勾号后，打开 Google Drive：文件 keystore.zip 位于 AAPS → KeyStore 文件夹中。如果运行在 Google Drive 步骤失败，说明 fork 的 Google Drive 访问权限已过期：参见 Google refresh token 已过期。

4. 下载 keystore.zip，使用 ZIP_PASSWORD 打开它：可以在电脑上打开，也可以在手机上使用能够打开受密码保护 ZIP 文件的文件管理应用。它包含：

   • keystore.jks：你的 keystore；

   • keyStoreInfo.txt：你的 KEYSTORE_PASSWORD、KEY_PASSWORD 和 ALIAS（通常为 key0）。

5. 将 keystore.jks 复制到手机（或复制到 Google Drive，以便之后从那里选择）。

在设置页面的第 3 步中：

1. 点击 I already have a keystore。

2. 在 Keystore file 中选择 keystore.jks。

3. 在 Keystore password 中输入 keyStoreInfo.txt 中的 KEYSTORE_PASSWORD。

4. 在 Key alias 中选择或输入 keyStoreInfo.txt 中的 ALIAS。

5. 如果 KEY_PASSWORD 与 KEYSTORE_PASSWORD 不同，取消勾选 Key password is the same as the keystore password，然后输入 KEY_PASSWORD。

将 keystore.zip 和其 ZIP_PASSWORD 一起安全地存放在手机之外：这是你的密钥备份。

fork 的 Google Drive 访问权限也无法复制。若要同时将 AAPS Builder 的构建结果保存到 Google Drive，请完成第 7 步。在手机安装使用 AAPS Builder 构建的 AAPS 之前，可以保留 fork。

打开设置页面

→ 打开 AAPS Builder 设置页面

请保持本文档页面打开：长按上面的链接并选择 Open in new tab。下面的步骤会更详细地解释设置页面的各个部分。

设置页面会在新的 Chrome 选项卡中打开每个 GitHub 页面。要返回设置页面，点击 Chrome 地址栏旁边的选项卡按钮（带数字的方框），然后选择 AAPS Builder 设置页面。

设置页面完全在浏览器中运行：你的密钥和密码不会发送到任何地方，除非你亲自将它们粘贴到 GitHub secret 中。只有你的 GitHub 用户名会发送到 GitHub，用于检查该用户名是否存在。它会记住你的 GitHub 用户名和仓库名称，因此你可以随时回来重新打开 secrets 页面或构建页面。

第 1 步 – 创建私有构建仓库

此步骤会在你的 GitHub 帐户中创建一个空的私有仓库。只有你能看到它及其构建的应用。

1. 确保你已在此浏览器中登录 github.com。

2. 在 Your GitHub username 中输入你的 GitHub 用户名，而不是电子邮件地址。页面会通过 GitHub 检查：显示 ✓ GitHub user found 表示正确。

3. 在 Name of your repository 中保留建议的名称 my-aaps。如果你已经用其他名称创建了仓库，请输入那个确切的名称。

   小技巧

   已经自行创建了空的私有仓库？ 在这里输入其确切名称，不要点击 Create my private repository，然后转到第 2 步。

4. 检查 Your repository: 一行，它应显示 github.com/<your username>/my-aaps。

5. 点击 Create my private repository。

   

6. GitHub 会在新选项卡中打开页面，其中 Owner 是你的帐户，名称是你选择的名称。

   

   向下滚动：Private、No template 和 Add README: Off 已经选好。不要更改任何内容，也不要添加 README 或其他文件。

7. 向下滚动并点击绿色的 Create repository 按钮。

   

   GitHub 会显示新建的空仓库。要进入第 2 步，请返回设置页面选项卡：点击 Chrome 地址栏旁边的选项卡按钮，然后选择设置页面。

第 2 步 – 添加构建工作流

构建工作流是一个简短的文本文件，用于告诉 GitHub 如何构建 AAPS。设置页面会将它添加到你的仓库中一次：你只需确认即可。

1. 确认页面显示 Workflow version … is ready，然后点击 Add the workflow to my repository。

   

2. GitHub 会在你的仓库中打开一个新文件，文件名已经是 .github/workflows/build.yml，内容也已填写好。检查顶部的文件名：必须正好是 .github/workflows/build.yml。不要更改文本。

3. 点击 Commit changes…

   

4. 然后在打开的窗口中再次点击 Commit changes。

   

   GitHub 会在仓库的 .github/workflows 文件夹中显示新文件 build.yml。

   

警告

文件编辑器打开时，不要按手机的 Back 按钮，也不要向下拉页面：GitHub 会重新加载页面，文本会消失。如果发生这种情况，请点击蓝色横幅中的 Restore，或者返回设置页面并再次点击按钮。

如果文本区域为空，请点击设置页面第 2 步底部的 Updating the workflow, or the text area is empty?：点击 Copy workflow，然后将其粘贴到文本区域（手机上请长按）。

警告

只能使用此设置页面提供的工作流。不要从其他网站或仓库复制构建工作流：该工作流会与签名密钥一起运行。

第 3 步 – 你的签名密钥

应用必须使用你自己的密钥签名。选择两个选项卡中的一个。请先阅读新密钥还是现有密钥警告。

I already have a keystore

1. 点击 I already have a keystore。

2. 在 Keystore file 中选择你的 .jks 文件（也可以是 .keystore、.p12 或 .pfx）。在手机上，请先将文件复制到手机或 Google Drive。

3. 在 Keystore password 中输入 keystore 密码。

4. 在 Key alias 中从列表选择别名；如果没有列表，则输入别名。使用 Android Studio 创建的 keystore 通常为 key0。

5. 如果密钥密码与 keystore 密码不同，取消勾选 Key password is the same as the keystore password，然后输入密钥密码。

6. 点击 Check and continue。

页面会在你的设备上检查密码和别名。显示 Keystore OK! Continue with step 4. 表示一切正确。如果页面提示密码将在构建时检查，也可以继续：如果有问题，构建时会告诉你。

Create a new key

1. 点击 Create a new key。

2. 设置一个密码并输入两次。规则：至少 8 个字符，只能使用字母 a–z 和 A–Z、数字 0–9 以及 ! ? # 等符号。不能包含空格、重音字母或 | 字符。

3. 点击 Create key。几秒钟后才会显示 Key created。

   

4. 点击 Download backup (aaps-keystore.jks)。如果 Chrome 询问 Download file again?，说明手机上已有同名的旧备份：点击 Download again。Chrome 随后会将新密钥保存为 aaps-keystore (1).jks：这是与该密钥对应的文件，请保留它，不要与旧文件混淆。

   将以下三项放在手机之外的安全位置（例如你自己的云存储）并保存到一起：

   • 文件 aaps-keystore.jks；

   • 你的密码；

   • 密钥的别名：key0。

   如果今后用其他方式（例如 Android Studio）构建 AAPS，需要这三项。使用设置页面早期版本创建的密钥，其别名为 aaps。

   

第 4 步 – 将密钥提供给仓库

完成第 3 步后，第 4 步会解锁。你的密钥、密码和别名会被打包为一个值，即 KEYSTORE_SET secret。

1. 点击 Open the secrets page。

2. GitHub 会打开仓库的 New secret 页面。在手机上，它位于设置菜单下方：向下滚动。

3. 切换到设置页面选项卡并点击 Copy name。切回 GitHub 选项卡，将其粘贴到较小的 Name 字段中。名称是 KEYSTORE_SET。

4. 切换到设置页面选项卡并点击 Copy secret。切回 GitHub 选项卡，将其粘贴到较大的 Secret 框中（手机上请长按）。secret 是一段非常长的代码，包含数千个字符：设置页面会在按钮旁边显示其开头字符。不要在那里粘贴 KEYSTORE_SET 这个单词。

5. 点击 Add secret。KEYSTORE_SET 现在会显示在 Repository secrets 下。

你只需要完成一次此操作。

小技巧

GitHub 显示 Page not found（404）？先检查你是否已在此浏览器中登录 github.com：未登录时，GitHub 对私有仓库会显示 404。否则，可能是第 1 步中的用户名或仓库名称与实际仓库不匹配。请在 github.com 上检查名称，在第 1 步中改正，然后再次点击按钮。

第 5 步 – 构建应用

1. 在设置页面点击 Open the build page。GitHub 会打开仓库的 Build AAPS 页面。

   

   如果打开的是 GitHub 应用：点击 RUN WORKFLOW，检查版本和变体，然后再次点击 RUN WORKFLOW。应用可能仍显示 Nothing to see here：向下拉列表刷新，即可看到你的构建。然后继续下面的第 4 步。

2. 如果 GitHub 提示，请点击绿色按钮启用工作流。

3. 点击 Run workflow。会打开一个小表单：

   • Version：保留 latest 以构建最新的 AAPS 发布版，或输入发布版本号，例如 3.3.2.1。

   • Variant：正常使用泵时保留 fullRelease。其他变体请参见构建变体的说明。不要选择 aapsclient3Release：AAPSClient3 只有从 AAPS 4.0 版本开始才存在。

   • 点击绿色的 Run workflow 按钮。

   

4. 构建开始并显示 In progress，包含两个部分：AAPS / Check，然后是 AAPS / Build AAPS。

   

5. 等待 15 到 30 分钟。绿色勾号表示构建完成。红色叉号表示失败：打开构建查看消息，然后参见故障排除。

   

   小技巧

   构建完成时发送电子邮件： GitHub 只会在构建失败时给你发送电子邮件。若要在构建成功时也收到邮件，请在 github.com 上打开头像 → Settings → Notifications → System → Actions，然后取消勾选 Only notify for failed workflows。

如果没有 Build AAPS 或 Run workflow 按钮：

• 打开你的仓库，检查文件 .github/workflows/build.yml 是否存在。如果缺失或名称不同，请重新完成第 2 步。

• 打开 Actions 选项卡。如果显示工作流已禁用，请点击绿色按钮启用它们，然后在列表中点击 Build AAPS。

第 6 步 – 将应用安装到手机

警告

每次更新前，请在 AAPS 中导出设置，并将文件复制到手机之外（Google Drive、Dropbox 等）。同时在那里保留几份较旧的导出文件和 APK 文件，这样随时都能回退。

1. 在手机上使用 Chrome 打开设置页面。如果页面询问，请登录 github.com。

2. 点击 Open my builds，然后点击最新的、带绿色勾号的构建。

   GitHub 应用而不是 Chrome 打开了？

   GitHub 应用无法下载构建结果。在应用中打开最新的构建，然后点击 Artifacts ↗；或者点击顶部的分享图标并选择 Chrome（也可以选择 Copy link，然后将链接粘贴到 Chrome 地址栏）。构建会在 Chrome 中打开：在那里继续下一步。

   若要停止让 GitHub 链接在应用中打开：进入 Android Settings → Apps → GitHub → Open by default → 关闭 Open supported links。

   

3. 向下滚动到构建摘要，然后点击 Download AAPS 链接。

   

   小技巧

   请在文字上用手指滚动，而不要在构建步骤图上滚动：滚动图会移动，而不是页面。

   你也可以继续向下滚动到 Artifacts，然后点击 aaps-….apk 旁边的下载图标。

   

4. 下载完成后，打开 Chrome 菜单 ⋮ → Downloads，点击 aaps-….apk 并选择 Install。如果页面询问，请允许从此来源安装应用。

   

aaps-wear-….apk 是智能手表应用。如果你不使用智能手表，可以跳过它。

应用会在构建页面保留 14 天。它不会显示在仓库的 Code 下。请将它与设置导出文件一起复制到手机之外的安全位置。

有关其他安装应用的方式，请参见传输和安装 AAPS。

备注

从 2026 年 9 月起，Google 的Android 开发者验证可能会根据所在国家/地区阻止通过点击文件安装 APK。该页面介绍了免费的解决方法。

第 7 步（可选）– 同时将应用保存到 Google Drive

你还可以将每次构建保存到 Google Drive 的 AAPS/<version> 文件夹中。这是可选的：应用始终可以从构建页面获取。

这需要另一个 secret：GDRIVE_OAUTH2。你可以使用其他浏览器构建方式所用的准备文件获取其值：

1. 在电脑上下载准备文件，并按照选项 1 – 电脑中的说明打开它。跳过 keystore 部分：你已经有了密钥。

2. 按照第 3 步 – 授权 Google Drive获取 GDRIVE_OAUTH2 值。

3. 在设置页面中，第 7 步会打开 secrets 页面。

   

   点击 Copy name，然后将其粘贴到较小的 Name 字段中（名称是 GDRIVE_OAUTH2）。将你的 GDRIVE_OAUTH2 值粘贴到较大的 Secret 框中，然后点击 Add secret。

从下一次构建开始，APK 也会保存到 Google Drive。

如果你 6 个月没有构建，或更改了 Google 密码，Google 会停止该访问权限。届时构建会提示你：重新完成这些步骤。参见 Google refresh token 已过期。

更新 AAPS

你的仓库不会自行构建任何内容：由你决定何时构建、构建哪个版本以及使用哪个变体。发布新的 AAPS 版本时：

1. 按照第 6 步的说明备份设置。

2. 按照第 5 步构建新版本。保留 latest，或输入发布版本号。

3. 按照第 6 步下载并安装。

**构建工作流更新：**你的仓库不会自行下载新的工作流，而且它运行的构建步骤固定在一个经过审核的版本上。当工作流发生变化时，文档更新和变更页面会说明。要更新工作流，请打开设置页面的第 2 步，然后点击 Updating the workflow, or the text area is empty?：

1. 点击 Copy workflow，然后点击 Open my workflow file。

2. 用复制的工作流替换全部文本（手机上请长按：Select all，然后 Paste）。

3. 点击 Commit changes…，然后点击 Commit changes。

文件的第一行显示其版本。

故障排除

要查看构建失败的原因，请在设置页面通过 Open my builds 打开该构建：图表下方的 Annotations 框会显示错误消息。要查看完整日志，请点击带红色叉号的作业，再点击带红色叉号的步骤。

• 更改 secret：打开仓库的 Settings → Secrets and variables → Actions，点击 secret 旁边的铅笔图标，粘贴新值，然后点击 Update secret。

• 修复后重新运行构建：打开失败的构建，点击顶部的 ⋯，然后点击 Re-run all jobs；或者按照第 5 步开始新的构建。

• 构建停止并显示“This repository is PUBLIC”：在仓库中打开 Settings → General → Danger Zone → Change visibility → Private，然后再次构建。

• “Secret KEYSTORE_SET is missing”：完成设置页面的第 4 步。

• “The secret is too short”、“The secret is not a valid code” 或 “The secret does not contain a keystore”：粘贴到了错误的文本，通常是粘贴了 KEYSTORE_SET 这个单词本身，或只粘贴了代码的一部分。在仓库中打开 Settings → Secrets and variables → Actions，编辑 KEYSTORE_SET，再次粘贴 Copy secret 提供的长代码（如果已关闭设置页面，先重新完成设置页面的第 3 步）。

• “Keystore, password or alias is wrong”：检查 keystore 的密码和别名，然后重新完成设置页面的第 3 步和第 4 步。

• “Version … does not exist”：输入的版本不是 AAPS 发布版本。使用 latest，或检查发布版本号。

• 设置页面打开 GitHub 时显示“Page not found”（404）：在同一个浏览器中登录 github.com（未登录时，GitHub 对私有仓库显示 404）。如果已登录，则说明设置页面第 1 步中的用户名或仓库名称与实际仓库不匹配。输入确切的名称。

• 第 1 步中显示“No GitHub user with this name”：输入 GitHub 个人资料中显示的 GitHub 用户名，而不是电子邮件地址。

• 没有 Download 链接，或打开了 GitHub 应用：GitHub 应用无法下载构建结果。按照第 6 步的说明在 Chrome 中打开构建。若要停止让 GitHub 链接在应用中打开：进入 Android Settings → Apps → GitHub → Open by default → 关闭 Open supported links。

• 设置页面显示“Could not read the workflow file”：重新加载页面并再次点击按钮。设置页面必须从此文档网站打开。

• 提交工作流时 GitHub 显示文件已存在：仓库中已经有一个工作流。按照更新 AAPS中的说明更新它。

• “Google Drive access has expired or was revoked”：重新完成第 7 步，并更新 GDRIVE_OAUTH2 secret。

其他 GitHub 和 Google Drive 问题，请参见浏览器构建故障排除。