solana-mobile

Solana Mobile 项目

搭建和维护 Solana Mobile 应用。solana-mobile CLI 负责项目脚手架、环境检查和模拟器管理——优先使用它，而不是手动搭建。

无需安装即可运行：

npx solana-mobile@latest --help

pnpm dlx solana-mobile@latest 和 bunx solana-mobile@latest 与之等效。使用项目已有的包管理器，并保留 @latest，以免运行器复用较旧的缓存版本。

命令	用途
create	搭建新项目
device	安装 APK、打开 URL、准备设备
doctor	检查工具链
emulator（emu）	创建和运行模拟器
localnet	设备可访问的本地验证器
playground	无需构建应用即可测试钱包
templates	维护模板仓库——仅适用于模板作者
webshell	将现有 Web 应用封装在 Android WebView 外壳中

所有命令的全部标志：请参阅 references/cli.md。不要猜测标志——CLI 自带帮助，任何命令上的 --help 都是权威说明。

不可妥协的限制

Mobile Wallet Adapter 需要开发构建。Expo Go 无法运行——MWA 依赖 Expo Go 未打包的原生 Android 模块。如果有人反馈在 Expo Go 中钱包连接失败，原因就在于此；没有其他解决方法，必须运行 expo run:android。

只有 Android 支持钱包。iOS 构建可以运行，但不支持 MWA。

首先：确定你属于哪种情况

情况	操作
还没有项目	创建新项目
已有 Expo 应用，但未集成 Solana	阅读 references/add-to-existing-app.md
项目已存在，但构建或工具链出现问题	检查环境
项目已存在，需要钱包功能	使用 solana-mobile-wallet 技能
需要测试钱包连接或签名	无需应用即可测试钱包

创建新项目

npx solana-mobile@latest create

默认采用交互模式。若要跳过提示，请指定项目名称和模板：

npx solana-mobile@latest create my-app --template expo-kit-wallet

实用标志：

标志	效果
-t, --template <id>	以非交互方式选择模板
--pm <manager>	要使用的包管理器
--minimal	使用最简模板
--list-templates	打印模板目录
--list-template-ids	将模板 ID 打印为 JSON 数组
--skip-install	不安装依赖
--skip-git	不初始化 git 仓库
-d, --dry-run	显示将执行的操作，不写入任何内容

选择模板

模板分为两个系列。请选择 expo-kit-* 模板。 @solana/kit 是当前的 Solana 客户端库，而这些模板也是 CLI 最积极维护的模板。

只有在用户有意继续使用现有的 @solana/web3.js 代码库，或明确点名要求时，才选择 expo-web3js-*。如果用户没有说明理由就提出要求，请先说明 kit 是更好的起点，再按其要求操作——使用 web3.js 开始的新应用从一开始就需要迁移。

expo-kit-minimal 最清晰地展示了 kit 各部分如何配合使用，即使使用其他模板构建，也值得阅读。

模板	技术栈	用途
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，或与 MWA 并用
expo-web3js-wallet	web3.js + MWA	旧版钱包应用
expo-web3js-paper	web3.js + RN Paper	旧版 Material UI
expo-web3js-minimal	web3.js	旧版基础起点

也可以使用完整的 gh:solana-mobile/templates/mobile/<name> 形式指定模板 ID。如果模板似乎缺失，请重新运行 --list-templates，不要仅凭此表判断——模板目录随 CLI 一同发布，而不随此技能发布。

脚手架搭建后

cd my-app && npm run android

这会运行 expo run:android，构建并安装开发版。首次 Android 构建较慢（Gradle 冷启动）；之后的构建会复用缓存。

检查环境

调试构建失败之前，先检查工具链：

npx solana-mobile@latest doctor

它会检查本地 Android 和 Node 工具链，并针对缺少的内容提供建议。--json 会输出稳定的报告，适合在需要根据特定检查结果进行分支处理时解析；--verbose 会附加解析后的路径和诊断信息。

如果构建失败的原因并非明显出在应用代码中，请先运行 doctor。

管理 Android 模拟器

npx solana-mobile@latest emu list
npx solana-mobile@latest emu status
npx solana-mobile@latest emu create
npx solana-mobile@latest emu start my_phone
npx solana-mobile@latest emu stop my_phone

emu 是 emulator 的别名。子命令包括：create、delete、images、list、start、status、stop、tune。系统映像位于 emu images 下（install、list、delete）。

在指定设备配置文件上创建命名模拟器：

npx solana-mobile@latest emu create local_phone --device pixel_9

准备全新的模拟器

新创建的 AVD 尚未准备好用于钱包工作：它尚未运行，首次启动对话框仍会弹出，也没有钱包应用。先启动并调整配置，再安装钱包——顺序很重要，因为 device install 需要设备已启动才能安装：

npx solana-mobile@latest emu start local_phone --tune
npx solana-mobile@latest device install fakewallet

--tune 会禁用动画、首次启动对话框、锁屏和通知，否则这些内容会遮挡全新 AVD 上的应用。调整配置需显式启用——只有传入 --tune 时，emu start 和 emu create --start 才会应用调整；以这种形式运行时不会交互，因此适合在脚本中使用。emu create 可通过 --start --tune 在创建时完成所有这些操作。

device install fakewallet 会将 Mobile Wallet Adapter 测试钱包安装到正在运行的模拟器上。没有钱包应用，MWA 就无法切换到钱包，连接操作也会悄无声息地无事发生——这是“在模拟器上点击连接毫无反应”最常见的原因。

任何需要 Seeker Genesis Token 才能使用的功能仍需在真实的 Seeker 设备上运行；模拟器无法持有该 Token。请参阅 seeker-genesis-token 技能。

使用已连接的设备

device 涵盖所有通过 adb 进行的操作，既适用于模拟器，也适用于实体手机。

npx solana-mobile@latest device list                       # serials, states, names
npx solana-mobile@latest device install fakewallet         # catalog APK
npx solana-mobile@latest device install ./app-release.apk  # local file
npx solana-mobile@latest device open http://localhost:3000 # opens on the device
npx solana-mobile@latest device tune --all -y              # prepare for automation

device open 会自行为 localhost URL 创建 adb reverse，因此 USB 连接的手机可以访问此计算机上的开发服务器。相比手动编写 adb reverse 和 am start 命令，优先使用它。

device tune 和 emu tune 会应用相同的调整，但有两点不同，其中第二点会影响脚本。device tune 接受实体设备，使用 --device <serial> 或 --all，并在只连接了一台设备时默认使用该设备。emu tune 不接受非模拟器序列号，将 AVD 名称或序列号作为位置参数；如果未提供参数，就会打开选择器——即使当前恰好只运行着一台模拟器也是如此，而且即使使用 -y 也一样：它会跳过调整提示，但不会跳过模拟器选择提示。在任何无人值守的操作中都应指定目标：emu tune local_phone -y。

运行本地验证器

npx solana-mobile@latest localnet start
npx solana-mobile@latest localnet check

localnet start 会在主机上运行验证器，并将其端口转发到每台已连接的设备，这样应用就能访问 localhost:8899，就像验证器运行在设备上一样。它会复用已启动的 localnet 容器，连接到已在这些端口上响应的验证器——包括无需 Docker 的原生验证器；只有两者都不存在时才会启动容器。 check 会验证每台设备是否都能访问验证器——当应用无法连接到明明正在此计算机上运行的验证器时，就应该检查这一点。

localnet forward 会在连接新设备后重新应用端口转发，logs、status 和 stop 则会执行其名称所示的操作。

不使用应用测试钱包

npx solana-mobile@latest playground

提供钱包测试页面，在设备上打开该页面，并将所有 MWA 交互实时输出到终端：连接、登录（SIWS）、签名消息、签名交易、签名并发送。默认使用 devnet；--cluster localnet 会将其指向 localnet 验证器；由于公共端点会拒绝来自浏览器源的请求，使用 mainnet 时需要提供自己的 --url。

用它来区分应用错误和配置错误。 如果该测试页面也无法签名，问题出在钱包或设备，而不是正在调试的代码。设备上必须安装 MWA 钱包——如果没有，可以使用 device install fakewallet。

参考资料

• references/cli.md — 所有 solana-mobile 命令和标志，包括 templates 和 webshell
• references/add-to-existing-app.md — 将 Solana 接入已有的 Expo 应用：加密 polyfill、提供程序、依赖项
• references/troubleshooting.md — 已知原因导致的构建、polyfill 和模拟器故障

相关技能

• solana-mobile-wallet — 连接钱包、签名、发送交易
• solana-mobile-publishing — 签署发布版 APK 并发布到 dApp Store
• seeker-genesis-token — 验证 Seeker 设备所有权
• seeker-domains — .skr 域名解析

对于一般的非移动端 Solana 工作——Anchor 或 Pinocchio 程序、Codama 客户端生成、测试、安全审查——请改用 Solana Foundation 的 solana-dev 技能。create 会将其安装到 .agents/skills/solana-dev/，因此脚手架生成的项目已包含该技能。

链接

• CLI 源码：https://github.com/solana-mobile/solana-mobile-cli
• 模板：https://github.com/solana-mobile/templates
• Solana Mobile 文档：https://docs.solanamobile.com