john
db5465c646
Stop embedding the 1.4MB bundle in index.html to avoid std::overflow_error on launch, validate the iOS asset build, and surface load failures in the native shell. Co-authored-by: Cursor <cursoragent@cursor.com>
53 lines
2.0 KiB
Markdown
53 lines
2.0 KiB
Markdown
# WordLoop iOS App
|
||
|
||
原生 iOS 壳应用，内嵌最新 Vue 前端构建产物，通过 `WKWebView` 展示，API 指向所选服务器。
|
||
|
||
## 与 H5 同步
|
||
|
||
Xcode 编译前会自动执行 `ios/scripts/build-web-assets.sh`，将 `frontend/` 最新代码构建并复制到 App 包内的 `www/`。因此首页（日常积累 / 词书练习双模式）、设置页（微信风格账号安全）等与本地 H5 保持一致，不依赖生产站是否已部署新版。
|
||
|
||
手动构建前端资源：
|
||
|
||
```bash
|
||
bash ios/scripts/build-web-assets.sh
|
||
```
|
||
|
||
## 服务器配置
|
||
|
||
| 环境 | API 地址 | 说明 |
|
||
|------|----------|------|
|
||
| **生产** | `https://w.tkmind.cn/api` | 默认环境 |
|
||
| **本地** | `http://127.0.0.1:18004/api` | 对应 `./start.sh` 后端；真机请改为电脑局域网 IP |
|
||
|
||
底部可展开切换服务器。界面与登录在同一 WebView，勾选「记住登录状态」后下次打开自动进入首页。
|
||
|
||
## 打开工程
|
||
|
||
```bash
|
||
open ios/WordLoop/WordLoop.xcodeproj
|
||
```
|
||
|
||
在 Xcode 中选择你的 **Team**（Signing & Capabilities），然后运行到模拟器或真机。
|
||
|
||
## 本地调试
|
||
|
||
1. 项目根目录启动服务：
|
||
|
||
```bash
|
||
./start.sh
|
||
```
|
||
|
||
2. iOS 模拟器：底部展开服务器栏，选「本地服务器」，默认 `http://127.0.0.1:18003`（API 自动映射到 18004）。
|
||
|
||
3. 真机：将本地地址改为 Mac 局域网 IP，例如 `http://192.168.1.8:18003`。
|
||
|
||
## 架构说明
|
||
|
||
- **原生层**：SwiftUI + WKWebView + 底部服务器栏
|
||
- **界面层**：内嵌 `frontend` 构建产物，经 `wordloop://` 本地协议加载（避免 `file://` 白屏）
|
||
- **数据层**：请求发往所选服务器的 `/api`
|
||
|
||
内嵌页通过 `loadFileURL` 加载 Bundle 内 `www/index.html`，`app.js` / `app.css` 为独立外链文件（**不要**内联进 HTML，否则 WebKit 解析超大 `<script>` 会触发 `std::overflow_error` 崩溃）。构建时脚本放在 `</body>` 前，确保 `#app` 已存在。
|
||
|
||
若出现白屏，请先执行 `bash ios/scripts/build-web-assets.sh`，再在 Xcode **Product → Clean Build Folder** 后重新 Run。
|