用 solana-mobile CLI 搭建、配置和排查…

在创建 Solana 移动应用、选择模板、为现有 Expo 应用接入 Solana、检查 Android 工具链、管理模拟器或真机、安装测试钱包、运行本地验证器或产出开发构建时使用。

适用场景

解决思路

1. 用 npx solana-mobile@latest --help 免安装运行 CLI；pnpm dlx solana-mobile@latest 和 bunx solana-mobile@latest 等价，匹配项目已有的包管理器并保留 @latest 以免复用旧缓存版本。
2. 按用途选命令：create 搭建新项目，device 安装 APK/打开 URL/准备设备，doctor 检查工具链，emulator（emu）创建和运行模拟器，localnet 起本地验证器，playground 无应用测试钱包，templates 供模板作者维护模板仓库，webshell 把现有 Web 应用包成 Android WebView 外壳。
3. 不要猜 flag，任何命令的 --help 都是权威来源，完整 flag 见 references/cli.md。
4. 牢记硬性约束：Mobile Wallet Adapter 必须用 development build，Expo Go 不行（缺少原生 Android 模块），钱包连接失败就是这个原因，只能改用 expo run:android；只有 Android 支持钱包，iOS 能构建但无 MWA。
5. 先判断所处情形：无项目→create；已有 Expo 应用无 Solana→读 references/add-to-existing-app.md；项目存在但构建/工具链坏了→doctor；需要钱包功能→用 solana-mobile-wallet 技能；要测钱包连接或签名→playground。
6. 创建项目：npx solana-mobile@latest create（默认交互式），跳过提示用 npx solana-mobile@latest create my-app --template expo-kit-wallet。
7. 常用 flag：-t/--template <id> 非交互选模板，--pm <manager> 指定包管理器，--minimal 用最小模板，--list-templates 打印模板目录，--list-template-ids 以 JSON 数组打印模板 id，--skip-install 不装依赖，--skip-git 不初始化 git，-d/--dry-run 只展示不写入。
8. 模板分两族，优先选 expo-kit-*（@solana/kit 是当前客户端库且维护最积极）；只有用户明确要延续 @solana/web3.js 代码库或点名要时才用 expo-web3js-*，否则先说明 kit 是更好的起点。expo-kit-minimal 是理解 kit 各部分如何组合的最清晰参考，即使基于别的模板也值得一读。
9. 模板选择：expo-kit-wallet（Kit + MWA + Uniwind，最佳默认，钱包连接/签名/发送已接好）、expo-kit-minimal（Kit，无 UI 套件的裸起点）、expo-kit-uniwind（Kit + Uniwind，Tailwind 风格样式，暂无钱包）、expo-kit-privy（Kit + Privy + Uniwind，用 Privy 认证替代或配合 MWA）、expo-web3js-wallet（web3.js + MWA，旧版钱包应用）、expo-web3js-paper（web3.js + RN Paper，旧版 Material UI）、expo-web3js-minimal（web3.js，旧版裸起点）。模板 id 也接受完整 gh:solana-mobile/templates/mobile/<name> 形式；若模板疑似缺失，重跑 --list-templates 而不是相信此表。
10. 脚手架完成后：cd my-app && npm run android（即 expo run:android，构建并安装 development build）；首次 Android 构建慢（Gradle 冷启动），后续构建复用缓存。
11. 构建失败且原因不在应用代码时，先跑 npx solana-mobile@latest doctor 检查 Android 和 Node 工具链并给出缺失项建议；--json 输出稳定报告便于按具体检查分支，--verbose 附加解析后的路径和诊断。
12. 管理模拟器：npx solana-mobile@latest emu list / emu status / emu create / emu start my_phone / emu stop my_phone；emu 是 emulator 的别名，子命令有 create、delete、images、list、start、status、stop、tune，系统镜像在 emu images（install、list、delete）下。
13. 在指定设备配置上创建具名模拟器：npx solana-mobile@latest emu create local_phone --device pixel_9。
14. 准备全新模拟器：新 AVD 未就绪（未运行、首次运行对话框还在、没有钱包应用），必须先启动并调优再安装钱包，顺序不能反（device install 需要已启动的设备）：npx solana-mobile@latest emu start local_phone --tune 然后 npx solana-mobile@latest device install fakewallet。--tune 会关闭动画、首次运行对话框、锁屏和通知；调优是 opt-in 的，emu start 和 emu create --start 只在传 --tune 时应用，这种形式非交互，适合脚本；emu create 接受 --start --tune 在创建时一次做完。device install fakewallet 把 MWA 测试钱包装到运行中的模拟器上；没有钱包应用时 MWA 无处交接，连接会静默无反应，这是模拟器上「连接没反应」最常见的原因。
15. 任何依赖 Seeker Genesis Token 的功能仍需真实 Seeker 设备，模拟器无法持有，见 seeker-genesis-token 技能。
16. 用 device 处理所有走 adb 的操作（模拟器和真机通用）：device list 列出序列号/状态/名称，device install fakewallet 装目录中的 APK，device install ./app-release.apk 装本地文件，device open http://localhost:3000 在设备上打开，device tune --all -y 为自动化做准备。
17. device open 会自行创建 adb reverse，使本机 dev server 可从 USB 连接的手机访问，优先用它而不是手写 adb reverse 加 am start。
18. device tune 与 emu tune 做同样的调整但有两点不同，第二点在脚本里会踩坑：device tune 接受真机，用 --device <serial> 或 --all，缺省回退到唯一连接的设备；emu tune 拒绝非模拟器序列号，以 AVD 名或序列号作位置参数，不给参数时会打开选择器——即使只有一个模拟器在跑、即使加了 -y（-y 只跳过调整提示，不跳过模拟器选择）。无人值守时务必指定目标：emu tune local_phone -y。
19. 运行本地验证器：npx solana-mobile@latest localnet start 让验证器在宿主机上服务并把端口转发到所有连接设备，应用可像验证器跑在设备上一样访问 localhost:8899；它会复用已启动的 localnet 容器、接入已在那些端口应答的验证器（原生验证器，完全不需要 Docker），两者都没有时才启动容器。npx solana-mobile@latest localnet check 验证每台设备的可达性——当应用看不到明明在本机运行的验证器时，这就是该问的问题。localnet forward 在插入新设备后重新应用转发，logs、status、stop 顾名思义。
20. 无应用测试钱包：npx solana-mobile@latest playground 提供钱包测试页、在设备上打开并把每次 MWA 交互（connect、sign in (SIWS)、sign message、sign transaction、sign and send）流式回终端；默认对 devnet，--cluster localnet 指向 localnet 验证器，mainnet 需自带 --url（公共端点拒绝浏览器来源请求）。用它区分应用 bug 和配置 bug：如果 playground 也签不了，问题在钱包或设备而非被调试的代码；它需要已安装 MWA 钱包，没有就 device install fakewallet。
21. 参考材料：references/cli.md 含所有 solana-mobile 命令和 flag（包括 templates 和 webshell）；references/add-to-existing-app.md 讲如何给已有 Expo 应用接入 Solana（crypto polyfill、providers、依赖）；references/troubleshooting.md 列出构建、polyfill、模拟器故障的已知原因。
22. 相关技能：solana-mobile-wallet（连接钱包、签名、发交易）、solana-mobile-publishing（签名 release APK 并发布到 dApp Store）、seeker-genesis-token（验证 Seeker 设备所有权）、seeker-domains（.skr 域名解析）；非移动端的通用 Solana 工作（Anchor 或 Pinocchio 程序、Codama 客户端生成、测试、安全审查）改用 Solana Foundation 的 solana-dev 技能，create 会把它装到 .agents/skills/solana-dev/，脚手架项目已自带。

适用边界 · 注意事项

• 需要 iOS 上的钱包功能时不适用——iOS 能构建但没有 MWA，钱包支持仅限 Android。
• 依赖 Seeker Genesis Token 的功能不适用——模拟器无法持有该 token，必须用真实 Seeker 设备。
• 非移动端的通用 Solana 开发（Anchor/Pinocchio 程序、Codama 客户端生成、测试、安全审查）不适用，应改用 solana-dev 技能。