主题
快速上手(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-bridgecrate 依赖- 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 的「构建」一节(不在本文档站内) |