Skip to content

快速上手(5 分钟) ​

第一次用 lynx-aura?三步走:生成 → 跑 Rust → 跑前端。


环境要求 ​

工具版本用途
Node.js≥ 18脚手架 / pnpm / Rspeedy
pnpm≥ 9前端包管理(项目根有 pnpm-workspace.yaml)
Rust≥ 1.75内核 / dev-server / 三端 .so

三端原生构建还需要对应 SDK(Android SDK+NDK / Xcode / OHOS SDK),见各自构建脚本。


第一步:生成项目 ​

bash
# 默认(不传 --mode):core 模式,项目自包含
# 生成时把 crates/ + packages/ 复制进项目 framework/core/,换机器、挪目录都不受影响
node scripts/create.mjs ../my-app --name "我的应用" --bundle-id com.acme.myapp --lib my_core

# 可选:
#   link 仅框架开发者用,项目直接引用本机框架目录(挪走会断)
node scripts/create.mjs ../my-app --mode link

默认 core:生成完就不再引用本机框架目录,可以单独提交、单独拷走。 core / link 都依赖 packages/*/dist,生成前需在框架仓库跑一次 pnpm -r build (缺 dist 时脚手架会直接报错提示)。

默认 core 模式生成后的项目结构:

my-app/
├── README.md                项目详细开发教程
├── package.json
├── pnpm-workspace.yaml
├── framework/              框架副本:core/(crates + packages)、build/(打包脚本)、README.md(内核教程)
├── config/                 项目配置:env / version / store / signing
├── frontend/               ReactLynx 应用(TabBar + SubPage + 主题 + i18n)
├── rust/                   业务内核(build_router + aura-dev-server 入口)
├── platforms/android/      Lynx 壳(MainActivity + BridgeModule)
├── platforms/ios/          XcodeGen 壳(MainViewController + NativeBridge)
├── platforms/harmony/      DevEco 壳(LynxPage + NAPI 包装层)
├── dist/                   构建产物(构建后生成,不入库)
└── scripts/                update-core.mjs 框架升级脚本

生成后先读项目的 README.md 完成第一个前后端功能;需要查内核 API 或扩展能力时读 framework/README.md。

第二步:装依赖 + 起 Rust dev-server ​

bash
cd my-app
pnpm install

# 终端 A:起 aura-dev-server(3456)
pnpm dev:rust
# 期望输出:
#   [info][db] database ready
#   aura-dev-server listening on http://127.0.0.1:3456

第三步:起前端 ​

bash
# 终端 B:起 Rspeedy(会连到 3456)
pnpm dev:frontend
# 期望输出:
#   ➜  Local:  http://localhost:3000/

浏览器打开 http://localhost:3000 就能看到应用。Home 页会显示桥接状态(NativeModule 模式才会是 native,否则 dev 模式显示 http)。


发生了什么? ​

dev 模式下:浏览器跑 Lynx,Rust 起 HTTP 桥在 3456,@aura/bridge-client 走 POST /dispatch 路由分发。两边共享同一个 build_router()——所以 dev 和真机永远走同一份 handler。

真机上:LynxView 跑 bundle,Rust 编成 .so 链进原生壳,NativeBridge 走 JNI(Android)或 C ABI(iOS/鸿蒙)调 aura_dispatch。传输层变了,内核分发逻辑没变。

         dev 模式                        真机模式
浏览器 ──HTTP /dispatch──> aura-dev-server ─┐
                                             ├─→ Aura::dispatch() ─→ 你的 handler
LynxView ──NativeModule──> NativeBridge ─────┘

可选 Features ​

生成项目时加 --features 参数,启用额外能力:

WiFi 局域网传输(wifi-bridge) ​

bash
node scripts/create.mjs ../my-app --features wifi-bridge
# 或者在 app.config.json 里把 generator.features 设为 ["wifi-bridge"](生成时字段,需重新生成项目)

启用后自动生成:

  • aura-wifi-bridge crate 依赖
  • Rust 侧 /wifi/start、/wifi/stop、/wifi/status 三个路由
  • Android 壳里加 WifiTransferService 前台服务类 + AndroidManifest 权限与 service 声明

用法:App 调 /wifi/start 拉起服务 → 电脑浏览器打开 http://<设备IP>:30000 上传。 文件落到 upload_dir(默认 AppPaths.data_dir/uploads)。

框架只负责文件落盘 + 任务状态 + HTTP 服务 + Web 页面;上传后的业务处理 (入库 / 解析 / 刷新 UI)由项目自己写。注意:上传完成不会自动推事件, 需要业务侧轮询 /wifi/status 的 tasks,或自行加钩子。

完整说明见 wifi-bridge.md(HTTP API、Rust API、前端调用、Android 前台服务接线、已知限制)。


下一步去哪 ​

你想…看
在 Rust 侧加一个新路由rust-side.md
前端怎么调后端、怎么订阅事件frontend-side.md
用 WiFi 让电脑给设备传文件wifi-bridge.md
升级项目里的框架内核项目内 node scripts/update-core.mjs --ref <tag>(步骤见变更记录)
打 Android / iOS / 鸿蒙安装包仓库根 README.md 的「构建」一节(不在本文档站内)

lynx-aura · 跨平台本地应用开发框架