用 dapp-store CLI 构建、签名并发布…

当需要把 Solana 移动应用发布到 dApp Store（首次上架、发更新、签名 release APK、注册 publisher 与 App NFT、或调试 release 构建正常但 debug 正常的问题）时使用。

适用场景

解决思路

1. 安装 CLI：npm install -g @solana-mobile/dapp-store-cli@latest（需 Node 18+；也可用 npx @solana-mobile/dapp-store-cli）。必须使用 1.0.1 或更新版本，旧版本已废弃不可用。
2. 只构建 APK，绝不构建 .aab：用 assembleRelease，不要用 bundleRelease（.aab 会被拒绝）。
3. 把 keystore 和 publisher 钱包都视为永久资产：更新必须用与上一版相同的 key 签名，App NFT 存在于 publisher 钱包中；两者都不要放进仓库，生成 keystore 前先确认它应存放的位置。
4. 如果同时发布到 Google Play，使用不同的签名 key（每个商店一个 key）。
5. 先判断所处情形：无 publisher 账号→做一次性设置；已有 publisher 要发版→构建签名 APK 后发布；发更新→走更新流程；release 崩溃但 debug 正常→查 references/signing.md#release-only-failures；发布中途失败→恢复失败的发布；是包装的 Web 应用→走 Web apps 流程。
6. 一次性设置：先确定 publisher keypair 文件（CLI 用 keypair 文件签名，浏览器钱包连接不会产生文件），且 portal 中连接的 wallet 必须与这个 key 相同；若已有 keypair 就用其路径，并先询问是哪一个，不要随手用 ~/.config/solana/id.json（通常是临时开发 key）。
7. 若还没有 keypair，由开发者本人生成（不要由 agent 生成）：solana-keygen new --silent --outfile ~/.config/solana/publisher.json；--silent 抑制助记词输出，否则十二个词会进入 stdout（即 transcript 和日志）。只在输出不被记录的终端里去掉 --silent，并无论如何备份该 keypair 文件；agent 只应拿到路径。
8. 把该 keypair 文件当作 release keystore 一样对待：放进 secrets store 或密码管理器，绝不放进仓库。
9. 注册 publisher：把该 keypair 导入一个长期控制的钱包，用它到 https://publish.solanamobile.com 注册；portal 会创建 publisher、收集 dApp 列表信息并铸造 App NFT。
10. 注意创建 listing 与铸造 App NFT 是两步，CLI 两者都做不了（它只发布已存在应用的版本）；若 listing 填了但 App NFT 未铸造，会在发布第 2 步报错 App NFT and wallet authority must exist before publishing a version。首次发布前确认 listing 同时有 App NFT 和 wallet authority。
11. 开始前给钱包充值：portal 目前约需 0.2 SOL 覆盖交易费和元数据存储（以 portal 实际报价为准，随 rent 和存储价格浮动）；这与 CLI 自身 preflight 要求的 0.016 SOL 是分开的。
12. 在 Dashboard > Settings > API keys 铸造 API key 并放入环境：export DAPP_STORE_API_KEY='paste-the-portal-api-key'（CLI 默认读取该变量）。交互式输入会进入 shell 历史，优先从 secrets manager 读取；可用 --api-key-env <name> 指定其他变量，或在 CI 中用 --api-key-stdin 从 stdin 读取：printf '%s' "$DAPP_STORE_API_KEY" | dapp-store --api-key-stdin <publish flags>。
13. 指向非生产 portal 的 flag：--local-dev 允许 localhost portal 并跳过 self-update 门禁；--skip-self-update 单独使用会报错 --skip-self-update is only allowed together with --local-dev，必须与 --local-dev 同用。local-dev 模式拒绝非本地 portal URL，要访问托管 staging portal 请用 --portal-url。
14. 构建签名 APK（EAS 托管凭据）：用 dapp-store profile 构建，它强制产出 APK：eas build --platform android --profile dapp-store；EAS 签名后返回下载 URL（没有 android/app/build/outputs/ 路径）。可下载产物后发布本地文件，或把 URL 传给 --apk-url 跳过下载；但发更新时要下载，因为 --apk-url 会跳过签名校验。
15. 构建签名 APK（本地签名，bare React Native 或本地 Expo）：(cd android && ./gradlew :app:assembleRelease)；子 shell 很重要，否则 cd 会持续生效，后续所有相对仓库根目录的路径都会在 android/ 下解析而失败。APK 输出在 android/app/build/outputs/apk/release/app-release.apk。
16. 上传前确认 APK 由预期 key 签名："$ANDROID_HOME"/build-tools/<version>/apksigner verify --print-certs "$APK"；apksigner 不在 PATH 上，位于 $ANDROID_HOME/build-tools/<version>/，选已安装的最高版本。apksigner verify 只读 APK，不需要 keystore 或私钥，因此对下载的 EAS 产物同样有效。
17. 发更新时，把打印的 SHA-256 指纹与上一版对比——这是上传前唯一能发现用错 keystore 的方式，而更新用错 key 是唯一无法恢复的失败。
18. 看证书名而不只是退出码：Expo 默认 prebuild 会把 release variant 接到 debug keystore，未配置的 release APK 会被 apksigner verify 顺利通过；若打印的 DN 是 CN=Android Debug，说明签名配置未生效，见 references/signing.md#gradle-signing-config。
19. 上传前检查体积：默认 React Native release APK 打包所有 ABI，常超过 100 MB；用 ./gradlew :app:assembleRelease -PreactNativeArchitectures=arm64-v8a 只构建一个架构通常能减半以上。
20. 发布（首次和后续每次都用同一条命令）：dapp-store --apk-file "$APK" --keypair ~/.config/solana/publisher.json --whats-new "Initial release"。$APK 是构建产物文件（Gradle 输出路径或下载的 EAS 产物），没有默认值；EAS 构建 URL 可直接传给 --apk-url https://… 发布托管 APK 而无需本地副本。
21. --keypair <path> 选择 Solana 签名者，CLI 没有默认 keypair 路径，必须显式传入；--verbose 会打印 release 和 session 标识符，失败时正需要这些。
22. portal 自己驱动发布，无需为它配置 RPC；--rpc-url <url> 存在但从 --help 隐藏，只用于提交前检查签名者余额的 preflight。portal 默认 https://publish.solanamobile.com，用 --portal-url <url> 或 DAPP_STORE_PORTAL_URL 重定向（仅在 Solana Mobile 给了 staging portal 时需要）。
23. 重定向 portal 时必须同时重定向 RPC：preflight 无论 --portal-url 是什么都读 mainnet，所以 devnet 上的 staging portal 会在发布开始前拒绝已充值钱包并报 Signer <address> has 0.000000 SOL, but publishing needs at least 0.016000 SOL available；同时传 --portal-url 和 --rpc-url，例如 --portal-url https://staging.publish.solanamobile.com --rpc-url https://api.devnet.solana.com。
24. 注意 CLI 启动时调用 dotenv.config()，工作目录中的 .env 会静默提供该变量和 API key；在自己项目里方便，在克隆来的仓库里是风险（别人提交的 DAPP_STORE_PORTAL_URL 会把你的 API key 发到他们的主机，且只校验 HTTPS）。从不属于自己的仓库发布前先读 .env，并显式传 --portal-url 覆盖。
25. portal 从 APK 的 package name 推断要更新哪个应用，因此该名称必须与设置时创建的 listing 匹配，否则会表现为找不到应用而非命名错误。Expo 上名称来自 expo.android.package，bare 项目来自 android/app/build.gradle 的 applicationId，检查项目实际拥有的那个。
26. 脚本化发布时传 --idempotency-key <key>，并在该次发布的每次重试中复用同一个值；省略它不是中性默认——CLI 每次调用生成新的 randomUUID()，重试会被当成新发布而可能重复发布。首次尝试前就把该 key 与 release id 一起记录。
27. 恢复失败的发布：发布是多步 session，失败是否留下可恢复内容取决于死在哪一步。在铸造步骤失败会被回滚，CLI 会打印 Rolling back failed publication release / Failed publication release cleaned up，此后没有 session，应重新发布。只有在运行未清理就死掉（通常是网络中断）时才用 dapp-store resume --release-id "$RELEASE_ID" --keypair ~/.config/solana/publisher.json。
28. resume 会像 publish 一样校验 --keypair，缺了会报 --keypair is required；--release-id 与 --session-id 必须恰好传一个，两个都传会被直接拒绝（尽管 --help 的用法行把它们显示在一起）。
29. 两个标识符都来自原始运行的输出，这就是非交互场景要加 --verbose 的理由。注意 --verbose 打印的时机：release id 和 publication session id 只在 APK ingestion 成功后输出；在 ingestion 期间死掉的运行只打印 ingestion session id，那是不同的标识符，--session-id 要的是 publication session id 且不接受它；那么早的失败本来也无从恢复，修好原因重新发布即可。
30. 发更新：命令与首次发布相同，但必须满足三点，否则失败或静默地什么都没更新。
31. 发更新第 1 点：提升 versionCode，但要在真正拥有它的文件里改。bare 项目是 android/app/build.gradle；Expo 是 app.json 或 app.config.* 中的 expo.android.versionCode，在 Expo 里改 build.gradle 无意义，因为 prebuild 会重新生成。新脚手架 Expo 应用常常在 app.json 里既没有 expo.version 也没有 expo.android.versionCode，Expo 会回退到 1.0.0 和 1；应在首次发布前就加上这两个 key，而不是等第二次发布需要更高值时才发现缺失。若 cli.appVersionSource 为 "remote"，versionCode 完全由 EAS 拥有：在 build profile 上设置 autoIncrement，不要改任何本地文件。Android 按这个整数排序发布，商店也用它判断哪个更新。
32. 发更新第 2 点：同时提升 versionName——Expo 上是 expo.version，bare 项目是 build.gradle 中的 versionName。CLI 会把两者作为发布元数据提交，versionName 是用户在 listing 中看到的字符串；不改不会被拒绝，所以只改 versionCode 的更新会静默地仍显示旧版本。
33. 发更新第 3 点：用原始 keystore 签名（见前述约束，无法恢复）。
34. 审核：提交后进入人工审核，需几个工作日（以文档当前数字为准，不要按此处引用的数字安排发布）。常见拒绝原因：APK 未签名、package name 与 listing 不匹配、缺少隐私政策、内容超出 publisher policy；最后一项以 policy 为准且会变化，应阅读而非猜测。
35. Web 应用走不同路线：web manifest、Bubblewrap 构建，以及在 /.well-known/assetlinks.json 发布 Digital Asset Links。只有应用确实是待包装的 PWA 时才走这条路；React Native 应用走上面的原生 APK 路径，Bubblewrap 只会增加一层并破坏 Mobile Wallet Adapter。完整流程见 https://docs.solanamobile.com/recipes/general/publishing-a-web-app。
36. 参考材料：references/signing.md 涵盖 keystore 创建、Gradle 签名配置、EAS build profile，以及 release 专有失败（含 ProGuard 陷阱）。相关技能：solana-mobile（脚手架、工具链检查、开发构建）、solana-mobile-wallet（必须在 release 构建中存活的钱包集成）。

适用边界 · 注意事项

• 应用是 React Native 原生应用时不要走 Web apps/Bubblewrap 路线，那只会增加一层并破坏 Mobile Wallet Adapter。
• 不要用 .aab 或 bundleRelease 构建，dApp Store 只接受 APK。
• 不要用 ~/.config/solana/id.json 等临时开发 key 或与 Google Play 共用的签名 key 来签名发布。