使用 GitHub 登录
ZH

手把手教你上架 Play 商店

把 JumPHP 游戏放上 Google Play 并长期维护的完整使用说明：需要构建什么、需要保管什么、需要在手机上检查什么，以及 Play Console 的全流程。它适用于两种应用：

网页应用（上架 Google Play） 原生应用（原生 Android 应用）
命令 bin/jumphp twa mon-jeu --url https://jumphp.net/mon-jeu bin/jumphp android mon-jeu
它是什么 Chrome 中的游戏页面，全屏 PHP、SDL 和游戏都在应用内，无需网络
游戏如何更新 随网站立即更新（不需要新应用） 需要发布新版本的应用

你的 Claude 了解这份指南（它在你项目的 AGENTS.md 和 docs/google-play.md 中）：对它说“把我的游戏上架 Google Play”即可。技术工作由它完成；各项选择和提交仍由你来决定（见末尾）。

0. 开始之前

  • 一个 Google Play 开发者账号：play.google.com/console，一次性 25 美元，需要身份验证。这是你的账号：由你来接受 Google 的条款。
  • 新的个人账号必须先进行至少 12 名测试人员、为期 14 天的封闭测试，才能发布到正式版。请尽早开始。
  • 包名（io.github.<你的 github 账号>.<mon_jeu>）：应用在 Google Play 上的标识。它之后永远不能更改。命令会在第一次运行时询问。
  • Android SDK 许可协议：由你在自己的终端中接受，第一次时进行（SDK 约 1 GB，存放在 ~/.jumphp 中）。你的 Claude 会请你自己运行该命令（! bin/jumphp twa …）。
  • 一个公开地址上的隐私政策：即使游戏什么都不收集，Google 也会要求提供。一个简短的页面就够了：游戏不收集、不发送、不分享任何个人数据；没有账号，没有广告，没有追踪；设置和存档都留在设备上；附上一个联系邮箱。把它放进游戏的网站中，即 games/mon-jeu/site/privacy.html：它会通过 https://play.jumphp.net/mon-jeu/privacy.html 提供访问（或者使用你公开仓库中的 PRIVACY.md）。把地址交给 Google 之前，请先打开一次这个地址：404 错误会导致审核无法通过。

1. 密钥：请先备份

第一次构建会创建你的上传密钥：~/.jumphp/android/keys/<包名>.keystore，其密码在 <包名>.env 中。

  • 绝不要放进 git，也不要放进笔记或消息中。把这两个文件备份到别处（密码管理器、加密磁盘）。没有它们，重新构建会创建另一把密钥，Google Play 会拒绝更新。
  • 使用 Google Play 应用签名（默认）时，Google 会保管它自己的密钥，也就是在手机上为应用签名的那把。你的密钥只用来证明上传来自你；丢失后 Google 可以替换它（设置 > 应用签名），但这需要几天时间。
  • 因此会有两个 SHA-256 指纹：你的密钥的（由命令显示）和 Google 密钥的（Play Console > 设置 > 应用签名，在第一次上传之后）。

2. 构建应用

bin/jumphp twa mon-jeu --url https://jumphp.net/mon-jeu     # 网页应用
bin/jumphp android mon-jeu                                   # 或原生应用
  • 每次构建都会让版本号加 1（Google Play 会拒绝已经上传过的版本号；一次失败的尝试会占用一个版本号，没关系）。
  • 请立即提交版本文件：games/mon-jeu/android/twa-manifest.json（网页应用）或 games/mon-jeu/android/app.json（原生应用）。绝不要提交 dist/。
  • 图标下方的名称：game.yaml 中的 pwa: {short_name: …}（12 个字符可以完整显示）。图标：assets/icon.png。

3. 仅网页应用：网站为应用担保

只有当网站声明了应用时，Android 才会以全屏方式打开页面：声明内容包括包名和两个指纹（你的和 Google 的）。如果只有你的指纹，通过你的 .apk 安装的应用可以正常工作，但从 Google Play 安装的应用打开时会带着地址栏（或者弹出“打开方式”的选择）。

在工作室中，进入游戏页面的 Android 应用部分（或让你的 Claude 使用 update_project）。网站会把它们发布到 https://jumphp.net/.well-known/assetlinks.json。在你自己的服务器上则是：https://你的域名/.well-known/assetlinks.json。

4. 在真机上试用

开启 USB 调试并使用 adb：

adb install -r games/mon-jeu/dist/android/mon-jeu-<version>.apk
adb shell pm get-app-links <paquet>          # 网页应用："jumphp.net: verified"
adb exec-out screencap -p > capture.png      # 看一看：游戏应该在里面
  • 应用应当打开到游戏的标题画面。
  • 用你的密钥签名的 .apk 无法覆盖安装来自 Google Play 的同一个应用（INSTALL_FAILED_UPDATE_INCOMPATIBLE）：请先卸载（应用的存档会丢失）。
  • 网页应用打开后立刻关闭，并弹出“打开方式”的选择：手机上有两个 Chrome，通常是因为存在分身空间 / 第二空间 / 应用双开（小米、三星……）。JumPHP 的应用会指定主用户空间的 Chrome，这样玩家就不会遇到问题；在你的测试手机上，删除分身空间会清除其中的所有应用。
  • 游戏能在 Chrome 中打开，并不能证明应用能正常工作：请亲自试用应用。

5. 第一次使用 Play Console

控制面板上的“设置你的应用”清单（X / 11）会显示还剩什么要做；只要还有缺项，“提交审核”就一直是灰色的。

  1. 创建应用：名称、默认语言、游戏、免费、各项声明。
  2. 应用内容（政策 > 应用内容），逐项声明：
    • 隐私政策：第 0 步中的公开地址；
    • 广告：没有广告（JumPHP 不会添加广告）；
    • 应用访问权限：无需任何特殊访问权限即可使用全部功能（没有账号）；
    • 目标受众：游戏面向的年龄段。选择 13 岁以下的年龄会让应用进入家庭计划（规则更严格，曝光更少）：只有当游戏确实是为儿童设计的才这么做；
    • 内容分级（IARC 问卷）：类别选“游戏”；请如实回答你的游戏的情况（卡通或奇幻暴力、血腥、恐怖、赌博、玩家创作的内容、玩家之间的交流、位置、购买）；
    • 数据安全：没有账号也没有统计功能的 JumPHP 游戏不会收集或分享任何数据（存档留在设备上；如果你的游戏调用了网络服务，请如实声明）；
    • 广告 ID：不使用；
    • 政府类应用、金融功能、健康：否。
  3. Play 商店设置（发展 > Play 商店展示 > 设置）：类别（街机、动作、益智……）和联系邮箱。两项都是必填：没有它们，会提示“Your app cannot be published yet”。该邮箱是公开的。
  4. 主要商店详情：标题（30 个字符）、简短说明（80）、完整说明（4000）、512 × 512 的 PNG 图标（bin/jumphp build 会生成：dist/web/icon-512.png）、1024 × 500 的图片、至少 2 张手机截图（bin/jumphp shot mon-jeu，按整数倍放大，或在手机上截取）。请把这些图片保存在游戏中（games/mon-jeu/store/），以便在后续版本中重新制作。
  5. 测试：测试和发布 > 测试 > 内部测试（新账号为满足 12 名测试人员，则选封闭测试）> 创建版本 > 上传 .aab > 版本说明 > 保存 > 审核 > 开始发布。测试人员：一个邮箱地址列表；每个人用该 Google 账号登录后打开邀请链接，点击成为测试人员。
  6. 网页应用：第一次上传之后，请添加 Google 密钥的指纹（第 3 步），通过测试链接安装并检查是否全屏。
  7. 正式发布：正式版 > 国家 / 地区 > 添加，选择后保存（没有国家的版本会被拒绝），然后创建版本 > 上传 .aab > 说明 > 下一步 > 保存。
  8. 发布概览 > 提交审核，并确认。审核需要几小时到 7 天；控制台和账号邮箱会告诉你应用何时上线。

6. 版本说明

每种语言一个块，标签单独占一行：

<fr-FR>
Première version.
</fr-FR>
<en-US>
First release.
</en-US>

7. 后续版本

  • 网页应用：游戏随网站更新（你推送，它就发布）：不需要新应用。只有当名称、图标、颜色、起始地址或包名变化时，才需要新应用：bin/jumphp twa mon-jeu。
  • 原生应用：游戏的每次变更都是一个新应用：bin/jumphp android mon-jeu --version-name 1.1。

然后：提交版本文件，在手机上试用 .apk，再进入 Play Console > 同一轨道 > 创建版本 > 新的 .aab > 说明 > 提交审核。各项声明仍然有效，除非游戏的改动涉及它们所描述的内容（在线游戏、购买、数据）：那就请先更新声明。

8. 遇到过的陷阱

现象 原因与解决办法
应用打开时带着地址栏 网站上缺少指纹（Google 的）或包名：见第 3 步
网页应用打开后立刻关闭 手机上有两个 Chrome（分身空间）：见第 4 步
INSTALL_FAILED_UPDATE_INCOMPATIBLE 已安装的应用来自 Google Play（另一把密钥）：请先卸载
“版本号已被使用” 重新构建（版本号 + 1）
Google Play 拒绝更新所用的密钥 上传密钥丢失或被重新创建：恢复备份，或请 Google 重置它
“Your app cannot be published yet” Play 商店设置：类别和联系邮箱
“提交审核”是灰色的 “设置你的应用”中还有一步没完成；或者有版本没有选国家
“请至少上传 1 个素材” 图片已在素材库中，但没有关联到商店详情：请从素材库面板中添加
某位测试人员没有被添加 输入邮箱地址后按回车（出现标签），然后保存并确认
隐私政策被拒绝 其地址返回 404 或不是公开的：请在无痕模式下打开它

你的 Claude 不会在没有你的情况下做的事

  • 接受 Android SDK 许可协议、Google 的条款，或者在不告诉你答案的情况下填写分级问卷；
  • 选择目标受众（说游戏“面向儿童”会改变规则和曝光）；
  • 在没有你对这一次提交明确同意的情况下发布到正式版；
  • 删除手机上的分身空间或卸载应用（会丢失数据）；
  • 把密钥、密码或 dist/ 放进 git。