solana-mobile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Solana Mobile projects

Solana Mobile 项目

Set up and maintain Solana Mobile apps. The

solana-mobile

CLI does the scaffolding, environment checks, and emulator management — prefer it over hand-rolled setup.

Run it without installing:

bash

npx solana-mobile@latest --help

pnpx solana-mobile@latest

and

bun x solana-mobile@latest

work too. Match whichever package manager the project already uses.

搭建并维护Solana Mobile应用。

solana-mobile

CLI可完成脚手架搭建、环境检查和模拟器管理——优先使用该工具而非手动配置。

无需安装即可运行：

bash

npx solana-mobile@latest --help

pnpx solana-mobile@latest

和

bun x solana-mobile@latest

同样可用。选择项目已在使用的包管理器即可。

Non-negotiable constraint

不可妥协的限制条件

Mobile Wallet Adapter requires a development build. Expo Go will not work — MWA depends on native Android modules that Expo Go does not bundle. If someone reports wallet connection failing in Expo Go, that is the cause; there is no workaround, they need

expo run:android

Android is the only platform with wallet support. iOS builds run, but no MWA.

Mobile Wallet Adapter 需要开发构建版本，Expo Go 无法正常使用——MWA依赖Expo Go未打包的原生Android模块。如果有人反馈在Expo Go中钱包连接失败，这就是原因；没有解决办法，必须使用

expo run:android

。

Android是唯一支持钱包的平台。iOS可构建运行，但不支持MWA。

First: work out which situation you are in

第一步：确定你的场景

Situation	Do this
No project yet	Create a new project
Existing Expo app, no Solana	Read references/add-to-existing-app.md
Project exists, build or toolchain broken	Check the environment
Project exists, needs wallet features	Use the `solana-mobile-wallet` skill

场景	操作
尚无项目	创建新项目
已有Expo应用，未集成Solana	阅读 references/add-to-existing-app.md
项目已存在，构建或工具链故障	检查环境
项目已存在，需要钱包功能	使用 `solana-mobile-wallet` 技能

Create a new project

创建新项目

bash

npx solana-mobile@latest create

Interactive by default. To skip the prompts, name the project and template:

bash

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

Useful flags:

Flag	Effect
`-t, --template <id>`	Pick a template non-interactively
`--pm <manager>`	Package manager to use
`--minimal`	Use the minimal template
`--list-templates`	Print the template catalog
`--list-template-ids`	Print template ids as a JSON array
`--skip-install`	Do not install dependencies
`--skip-git`	Do not initialise a git repo
`-d, --dry-run`	Show what would happen, write nothing

bash

npx solana-mobile@latest create

默认是交互式操作。若要跳过提示，需指定项目名称和模板：

bash

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

实用标志：

标志	作用
`-t, --template <id>`	非交互式选择模板
`--pm <manager>`	指定使用的包管理器
`--minimal`	使用极简模板
`--list-templates`	打印模板目录
`--list-template-ids`	以JSON数组形式打印模板ID
`--skip-install`	不安装依赖项
`--skip-git`	不初始化git仓库
`-d, --dry-run`	展示操作内容但不实际写入

Choosing a template

选择模板

Templates come in two families. Pick an
expo-kit-*
template.

@solana/kit

is the current Solana client library, and these are the templates the CLI maintains most actively.

Reach for

expo-web3js-*

only when the user is deliberately continuing an existing

@solana/web3.js

codebase, or asks for it by name. If they ask without a reason, say kit is the better starting point before going along with it — a new app on web3.js starts life needing a migration.

expo-kit-minimal

is the clearest reference for how the kit pieces fit together, and worth reading even when building on a different template.

Template	Stack	Use for
`expo-kit-wallet`	Kit + MWA + Uniwind	Best default. Wallet connect, sign, send already wired
`expo-kit-minimal`	Kit	Bare starting point, no UI kit
`expo-kit-uniwind`	Kit + Uniwind	Tailwind-style styling, no wallet yet
`expo-kit-privy`	Kit + Privy + Uniwind	Privy auth instead of, or alongside, MWA
`expo-web3js-wallet`	web3.js + MWA	Legacy wallet app
`expo-web3js-paper`	web3.js + RN Paper	Legacy, Material UI
`expo-web3js-minimal`	web3.js	Legacy bare starting point

Template ids are also accepted in full

gh:solana-mobile/templates/mobile/<name>

form. Re-run

--list-templates

rather than trusting this table if a template seems missing — the catalog ships with the CLI, not with this skill.

模板分为两类。优先选择
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
`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

查看——模板目录随CLI发布，而非本技能文档。

After scaffolding

脚手架完成后

bash

cd my-app && npm run android

That runs

expo run:android

, which builds and installs the development build. The first Android build is slow (Gradle cold start); later builds reuse the cache.

bash

cd my-app && npm run android

该命令会执行

expo run:android

，构建并安装开发版本。首次Android构建速度较慢（Gradle冷启动）；后续构建会复用缓存。

Check the environment

检查环境

Before debugging a build failure, check the toolchain:

bash

npx solana-mobile@latest doctor

It reports on the local Android and Node toolchain with recommendations for anything missing.

--json

gives a stable report worth parsing when you need to branch on a specific check;

--verbose

adds resolved paths and diagnostics.

Run

doctor

first whenever a build fails for reasons that are not obviously in app code.

在调试构建失败问题前，先检查工具链：

bash

npx solana-mobile@latest doctor

该命令会报告本地Android和Node工具链的状态，并针对缺失项给出建议。

--json

参数会生成一份稳定的报告，适合在需要根据特定检查结果分支处理时解析；

--verbose

参数会添加解析后的路径和诊断信息。

每当构建失败原因并非明显来自应用代码时，先运行

doctor

检查。

Manage Android emulators

管理Android模拟器

bash

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

is an alias for

emulator

. Subcommands:

create

delete

images

list

start

status

stop

. System images live under

emu images

(

install

list

delete

Create a named emulator on a specific device profile:

bash

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

bash

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

。系统镜像相关操作在

emu images

下（

install

、

list

、

delete

）。

基于特定设备配置文件创建命名模拟器：

bash

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

Testing wallet flows on an emulator

在模拟器上测试钱包流程

A fresh emulator has no wallet app installed, so MWA has nothing to connect to. Install an MWA-compatible wallet APK into the emulator first, or test on a physical Android device. Anything gated on the Seeker Genesis Token needs a real Seeker device — see the

seeker-genesis-token

skill.

全新的模拟器未安装钱包应用，因此MWA没有可连接的对象。需先在模拟器中安装兼容MWA的钱包APK，或在物理Android设备上测试。任何依赖Seeker Genesis Token的功能都需要真实的Seeker设备——请查看

seeker-genesis-token

技能文档。

Reference material

参考资料

references/add-to-existing-app.md — wiring Solana into an Expo app that already exists: crypto polyfill, providers, dependencies
references/troubleshooting.md — build, polyfill, and emulator failures with known causes

references/add-to-existing-app.md — 向现有Expo应用集成Solana：加密兼容补丁、提供者、依赖项
references/troubleshooting.md — 已知原因的构建、兼容补丁和模拟器故障排查

Related skills

链接

CLI source: https://github.com/solana-mobile/solana-mobile-cli
Templates: https://github.com/solana-mobile/templates
Solana Mobile docs: https://docs.solanamobile.com

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

solana-mobile

Original

Translation

Solana Mobile projects

Solana Mobile 项目

Non-negotiable constraint

不可妥协的限制条件

First: work out which situation you are in

第一步：确定你的场景

Create a new project

创建新项目

Choosing a template

选择模板

After scaffolding

脚手架完成后

Check the environment

检查环境

Manage Android emulators

管理Android模拟器

Testing wallet flows on an emulator

在模拟器上测试钱包流程

Reference material

参考资料

Related skills

相关技能

Links

链接