t3code：基于Web技术栈的Electron+iOS跨端开发实践

1. 项目概述：t3code 是什么，它解决哪类开发者的实际痛点？

t3code 这个名字乍看像某个新出的 CLI 工具或开源项目代号，但结合当前全网搜索热度与高频共现词——CLI、Electron、web app、iOS——它并非一个已发布、有官方文档的成熟产品，而更接近于一个正在社区自发演进的跨平台开发工作流代称。我过去三年带过二十多个前端+桌面+移动端混合项目，见过太多团队在 Electron 封装 Web 应用后卡在 iOS 兼容性上，也反复被问：“为什么 Electron 写的工具在 macOS 上跑得好好的，一到 iOS 就完全唤不起？连图标都显示不了？”——t3code 正是这类问题催生出的实践集合体。

它的核心定位很明确：让基于 Web 技术栈（React/Vue + TypeScript）构建的轻量级开发工具，能以最小改造成本，同时支持 macOS/Linux/Windows 桌面端（Electron），并具备 iOS 端可部署、可调试、可签名的完整能力链路。注意，这里说的“iOS 端”不是指把 Electron 直接跑在 iPhone 上（技术上不可行），而是指：① 用同一套 Web UI 代码生成 PWA 或 WebView 容器应用；② 通过 Xcode 打包为 IPA；③ 支持开发者模式调试、图标资源合规、本地 localhost 服务桥接、设备模拟器联调等真实上线前环节。

为什么需要 t3code 这样的概念？举个真实场景：某 AI 工具团队用 React + Express 做了一个本地模型管理界面，用户双击 .app 就能启动，自动拉起本地 LLM 服务。但销售反馈，教育客户希望 iPad 上也能用——他们不会装 Mac，但 iPad 人手一台。这时候，如果重写一套 Swift/iOS App，人力周期至少 3 周；而用 t3code 思路，只需补 4 个关键动作：① 把 Electron 主进程逻辑抽成独立 Node.js 后端服务；② Web 前端适配 Safari 16+ 的 PWA manifest 和离线缓存；③ 配置 Xcode 工程模板，用 WKWebView 加载本地 HTML；④ 补齐 iOS 图标尺寸（包括 Spotlight、Settings、App Store 等 12 种规格）。实测下来，从决定做 iPad 版到提交 TestFlight，总共用了 3 天半，其中 2 天在调图标尺寸和 HTTPS 本地代理。

所以 t3code 不是一个 npm 包名，而是一套可复用的跨端工程契约：它强制约定 Web 层不依赖 Electron 特有 API（如remote、shell.openExternal），后端服务必须提供标准 HTTP 接口，所有平台共享同一份src/目录，仅通过构建时环境变量切换渲染容器。这种设计让团队不再纠结“该用 Electron 还是 Capacitor”，而是聚焦在“如何让同一套业务逻辑，在不同壳子里稳稳跑起来”。尤其适合内部工具、AI 辅助插件、数据可视化面板、低代码编辑器等对 UI 一致性要求高、但对原生性能无极致需求的场景。

2. 核心架构设计：为什么选择 Electron + Web + iOS 三端协同，而不是纯 WebView 或纯原生？

2.1 三端协同不是“为了跨端而跨端”，而是由真实交付压力倒逼出的技术选型

很多团队一开始会想：“既然目标是 iOS，那直接用 React Native 或 Flutter 不就完了？”——这确实是标准答案，但 t3code 的诞生恰恰源于对标准答案的反思。我去年帮一家芯片设计公司重构其 IP 核配置工具，他们原有 Electron 版本已稳定运行 2 年，50+ 工程师每天使用，UI 复杂度高（含 Canvas 波形图、拖拽连线、实时 JSON Schema 校验）。若切到 React Native，意味着：① 所有 Canvas 渲染逻辑要重写为 Skia 绘图；② 拖拽库需替换为 PanResponder + GestureHandler，手势响应延迟上升 80ms；③ JSON Schema 校验依赖的 ajv 库在 Hermes 引擎下内存泄漏严重，需降级版本并自行 patch。最终评估下来，迁移成本远超预期，且无法保证旧功能 100% 对齐。

t3code 的解法是“分层解耦”：把整个系统拆成三层——

• 表现层（Presentation Layer）：纯 HTML/CSS/JS，只调用标准 Web API（Fetch、Canvas 2D、Web Workers），禁用任何 Node.js 或 Electron 专属接口；
• 协调层（Orchestration Layer）：Electron 主进程 / iOS WKWebViewDelegate / Web 服务三者共用的协议层，定义统一消息格式（如{ type: 'model:load', payload: { path: '/models/llama.bin' } }），所有平台通过postMessage或window.webkit.messageHandlers发送；
• 执行层（Execution Layer）：各平台各自实现。Electron 调fs.promises.readFile，iOS 走NSBundle.mainBundle.path(forResource:)，Web 端走fetch('/api/model')。

这个架构的关键在于：表现层代码零修改即可在三端运行，差异仅存在于构建配置和少量胶水代码。我们用一个真实对比说明效果：

提示：t3code 架构最常被误解的一点是“它让 iOS 开发变简单了”。其实恰恰相反——它让 iOS 开发变得更规范、更可预测。因为所有业务逻辑都在 Web 层，Xcode 工程里只剩 3 个文件：ViewController.swift（加载 WKWebView）、AppDelegate.swift（处理 URL Scheme）、Info.plist（配置权限和图标）。没有业务代码，就没有崩溃风险，审核被拒概率大幅下降。

2.2 Electron 为何仍是桌面端不可替代的“最佳胶水”

尽管 Electron 被诟病内存占用高，但在 t3code 体系中，它承担着不可替代的“协议翻译器”角色。举个具体例子：iOS 无法直接访问本地文件系统（沙盒限制），但 Electron 可以。当用户在 iPad 上点击“打开模型文件”，t3code 的协调层会触发 iOS 端的UIDocumentPickerViewController，选中文件后，通过WKScriptMessageHandler将文件路径（如file:///var/mobile/Containers/Data/Application/.../Documents/llama.bin）传给 Web 层；Web 层再把这个路径发给 Electron 后端（通过fetch('http://localhost:3000/api/open?path=...')）；Electron 收到请求后，用fs.promises.readFile读取二进制内容，再以 Blob 形式返回给 Web 层。整个过程，Web 层只感知到一次 HTTP 请求，完全不知道背后是 iOS 文件选择器还是 Electron 文件系统。

这种设计带来的好处是：所有平台的错误处理逻辑统一。比如模型加载失败，Web 层永远只处理fetch().catch()，不用区分“iOS 文件路径无效”还是“Electron 权限不足”。我们甚至把错误码标准化：ERR_FILE_NOT_FOUND（404）、ERR_MODEL_CORRUPT（422）、ERR_MEMORY_LIMIT_EXCEEDED（413）。这样，前端同学写一个useModelError()自定义 Hook，就能在三端显示一致的提示文案和重试按钮。

注意：Electron 版本选择有强约束。必须用 v22+（Chromium 116+），因为旧版不支持WebCodecsAPI，而 t3code 的视频预览模块依赖VideoEncoder实现实时 H.264 编码。我们实测过，v21 的 Chromium 114 在 M1 Mac 上编码延迟高达 1200ms，v22 降到 180ms。这不是参数优化能解决的，是底层 Media Foundation 重构带来的红利。

2.3 iOS 端不是“妥协方案”，而是通过 Web 技术栈释放的增量能力

很多人把 iOS 端当成 Electron 的“降级版”，这是对 t3code 的最大误读。实际上，iOS 端在某些场景下能力更强。典型案例如“设备传感器调用”：Electron 默认不提供陀螺仪、加速度计 API，需额外装node-hid或serialport；而 iOS 的 WKWebView 通过DeviceOrientation和DeviceMotion事件，原生支持所有传感器，且精度更高（Apple A 系列芯片的 IMU 校准比普通 USB 设备准 3 个数量级）。我们在做 AR 模型标注工具时，直接用window.addEventListener('deviceorientation', ...)获取欧拉角，配合 Three.js 渲染，效果远超 Electron + WebRTC 的方案。

另一个常被忽视的优势是系统级集成深度。t3code 的 iOS 实现会主动注册 URL Scheme（如t3code://open?model=llama）和 Universal Links，这意味着：

• 用户点击邮件里的链接，自动唤起 App 并跳转到指定模型页；
• Siri Shortcuts 可直接触发“打开最新训练模型”指令；
• 通过NSFileProviderExtension，App 可作为 iCloud Drive 的第三方存储位置，其他 App 能直接“分享到 t3code”；

这些能力在 Electron 中要么不存在，要么需绕道 native node modules（如electron-osx-sign无法处理 Siri Shortcuts 配置）。而 t3code 的 iOS 工程里，只需在Info.plist添加 4 行配置，再写 20 行 Swift 处理application(_:open:options:)，就能全部启用。

3. 核心实现细节：从零搭建 t3code 工程的 7 个关键步骤

3.1 步骤一：初始化单仓库多平台结构（monorepo + pnpm）

t3code 的物理结构必须是 monorepo，否则无法保证三端代码同步。我们不用 Lerna，而用 pnpm workspace，因为它的硬链接机制能让node_modules在子包间真正共享，避免 Electron 渲染进程和 iOS Webview 加载同一份 React 时出现版本错乱。

目录结构如下：

t3code/ ├── packages/ │ ├── web/ # 表现层：React + Vite，输出 dist/ │ ├── electron/ # 协调层 + 执行层：Electron 主进程 + preload.js │ └── ios/ # iOS 工程：Xcode 项目，引用 web/dist/ 作为资源 ├── scripts/ │ ├── build-electron.ts # 构建 Electron 的脚本（含 icon 生成、打包） │ └── build-ios.ts # 构建 iOS 的脚本（含图标生成、plist 注入） ├── shared/ # 全局共享类型定义、工具函数（如 message protocol） └── turbo.json # TurboRepo 配置，加速跨包构建

关键点在于shared/目录：它存放所有跨平台通用代码，例如message.ts定义了协调层协议：

// shared/message.ts export type MessagePayload = { type: 'model:load' | 'export:png' | 'sensor:start'; payload: Record<string, any>; }; export type MessageResponse<T = any> = { success: boolean; data?: T; error?: string; }; // 所有平台都 import { sendMessage } from 'shared/message' export function sendMessage<T>(payload: MessagePayload): Promise<MessageResponse<T>> { if (typeof window !== 'undefined' && 'webkit' in window) { // iOS WKWebView return new Promise((resolve) => { window.webkit.messageHandlers.t3code.postMessage(payload); window.addEventListener('t3code-response', (e: CustomEvent) => { resolve(e.detail); }); }); } // Electron 渲染进程 return window.electronAPI.sendMessage(payload); }

实操心得：shared/目录严禁引入任何平台专属依赖（如fs、UIKit）。我们曾因在shared/utils.ts里不小心用了path.join()，导致 iOS 构建时报ReferenceError: path is not defined。后来强制规定：所有路径操作必须在执行层完成，shared/只处理纯数据逻辑。

3.2 步骤二：Web 层严格遵循“无平台假设”原则

这是 t3code 成败的分水岭。Web 层代码必须通过 ESLint 插件eslint-plugin-no-restricted-imports锁死所有危险导入：

// web/.eslintrc.json { "rules": { "no-restricted-imports": [ "error", { "patterns": [ "electron", "fs", "child_process", "os", "path", "process" ] } ] } }

同时，所有异步操作必须封装为可 mock 的函数。例如文件读取：

// web/src/services/fileService.ts export interface FileService { readFile(path: string): Promise<ArrayBuffer>; writeFile(path: string, data: ArrayBuffer): Promise<void>; } // 默认实现（Web 端用 fetch） export const defaultFileService: FileService = { readFile: async (path) => { const res = await fetch(`/api/files/${encodeURIComponent(path)}`); return res.arrayBuffer(); }, writeFile: async (path, data) => { await fetch(`/api/files/${encodeURIComponent(path)}`, { method: 'POST', body: data, }); } }; // Electron 端覆盖实现 export const electronFileService: FileService = { readFile: async (path) => { return await window.electronAPI.fs.readFile(path); }, // ... };

这样，组件里只依赖FileService接口，测试时可注入 mock 实现，生产时根据平台注入真实实现。我们用一个useFileService()Hook 统一管理：

// web/src/hooks/useFileService.ts import { useContext, createContext, useContext } from 'react'; import { FileService } from '../services/fileService'; const FileServiceContext = createContext<FileService | null>(null); export function FileServiceProvider({ children }: { children: React.ReactNode }) { const service = isIOS ? iosFileService : isElectron ? electronFileService : defaultFileService; return <FileServiceContext.Provider value={service}>{children}</FileServiceContext.Provider>; } export function useFileService() { const service = useContext(FileServiceContext); if (!service) throw new Error('useFileService must be used within FileServiceProvider'); return service; }

3.3 步骤三：Electron 端构建安全可靠的 preload.js

preload.js 是 Electron 的“信任边界”，t3code 要求它必须满足：① 不暴露 Node.js 全局对象；② 所有 IPC 通信经由白名单校验；③ 支持热更新调试。

我们的preload.js结构如下：

// electron/src/preload.ts import { contextBridge, ipcRenderer } from 'electron'; // 白名单定义 const allowedChannels = ['model:load', 'export:png', 'sensor:start'] as const; type AllowedChannel = typeof allowedChannels[number]; // 仅暴露必要 API contextBridge.exposeInMainWorld('electronAPI', { sendMessage: (channel: AllowedChannel, payload: any) => { // 校验 channel 是否在白名单 if (!allowedChannels.includes(channel)) { throw new Error(`Forbidden channel: ${channel}`); } return ipcRenderer.invoke(channel, payload); }, onMessage: (channel: AllowedChannel, callback: Function) => { ipcRenderer.on(channel, (event, ...args) => callback(...args)); } });

构建时，Vite 的build.rollupOptions需显式指定external，防止把electron打包进去：

// electron/vite.config.ts export default defineConfig({ build: { rollupOptions: { external: ['electron'], output: { globals: { electron: 'require("electron")' } } } } });

注意：contextBridge.exposeInMainWorld是唯一安全的暴露方式。绝对禁止window.require = require或window.process = process，这会让 XSS 攻击直接获得 Node.js 权限。我们曾发现某团队在 preload.js 里写了window.fs = require('fs')，结果一个 Markdown 渲染漏洞就能让攻击者读取用户 home 目录。

3.4 步骤四：iOS 端 WKWebView 配置与桥接实现

iOS 工程基于 Xcode 15 创建，最低支持 iOS 15.0（Safari 15 的 WebKit 版本足够新）。关键配置在ViewController.swift：

class ViewController: UIViewController { private var webView: WKWebView! override func viewDidLoad() { super.viewDidLoad() let config = WKWebViewConfiguration() config.preferences.javaScriptCanOpenWindowsAutomatically = true config.allowsInlineMediaPlayback = true // 注册消息处理器 config.userContentController.add(self, name: "t3code") webView = WKWebView(frame: .zero, configuration: config) view.addSubview(webView) // 加载本地 HTML if let url = Bundle.main.url(forResource: "index", withExtension: "html", subdirectory: "dist") { webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent()) } } } extension ViewController: WKScriptMessageHandler { func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) { guard message.name == "t3code" else { return } guard let body = message.body as? [String: Any] else { return } // 解析消息类型，转发给对应服务 switch body["type"] as? String { case "model:load": loadModel(payload: body) case "export:png": exportPNG(payload: body) default: break } } }

桥接的核心是WKScriptMessageHandler，它让 Web 层能向原生发送消息，但反过来——原生向 Web 层发消息——需用evaluateJavaScript：

func sendResponse(to webview: WKWebView, response: [String: Any]) { let json = try! JSONSerialization.data(withJSONObject: response) let jsonString = String(data: json, encoding: .utf8)! webview.evaluateJavaScript("window.dispatchEvent(new CustomEvent('t3code-response', { detail: \(jsonString) }))") }

实操心得：iOS 端最耗时的环节是图标和启动图配置。Apple 要求 12 种图标尺寸（从 20x20 到 1024x1024），且必须放在Assets.xcassets的特定 slot 里。我们写了个 Python 脚本scripts/generate-ios-icons.py，输入一张 1024x1024 PNG，自动裁剪生成所有尺寸并注入 xcassets。同样，LaunchScreen.storyboard 必须用 Auto Layout，不能用固定坐标，否则在 iPhone Pro Max 上会显示错位。

3.5 步骤五：统一构建流程与资源注入

t3code 的构建不是三个独立流程，而是一个流水线。核心脚本scripts/build-all.ts逻辑如下：

// scripts/build-all.ts async function buildAll() { // 1. 构建 Web 层（输出到 packages/web/dist/） await exec('pnpm build', { cwd: 'packages/web' }); // 2. 复制 dist 到 Electron 和 iOS 工程 await copy('packages/web/dist', 'packages/electron/dist'); await copy('packages/web/dist', 'packages/ios/t3code/Assets.xcassets/WebResources'); // 3. 构建 Electron（含图标生成、打包） await exec('pnpm build', { cwd: 'packages/electron' }); // 4. 构建 iOS（含 plist 注入、图标生成） await exec('pnpm build', { cwd: 'packages/ios' }); // 5. 生成跨平台文档 await generateDocs(); }

其中packages/ios/pnpm build脚本会执行：

# packages/ios/package.json "scripts": { "build": "node scripts/inject-plist.js && xcodebuild -workspace t3code.xcworkspace -scheme t3code -destination 'generic/platform=iOS' -archivePath ./build/t3code.xcarchive archive" }

inject-plist.js的作用是动态修改Info.plist，注入当前构建的版本号、Bundle ID、URL Scheme：

// packages/ios/scripts/inject-plist.js const plist = require('plist'); const fs = require('fs'); const plistPath = './t3code/Info.plist'; let content = plist.parse(fs.readFileSync(plistPath, 'utf8')); content['CFBundleVersion'] = process.env.npm_package_version || '1.0.0'; content['CFBundleIdentifier'] = 'com.yourcompany.t3code'; content['CFBundleURLTypes'] = [{ 'CFBundleTypeRole': 'Editor', 'CFBundleURLName': 't3code', 'CFBundleURLSchemes': ['t3code'] }]; fs.writeFileSync(plistPath, plist.build(content));

3.6 步骤六：本地开发调试的 localhost 代理方案

开发时，Web 层需同时支持：① Electron 渲染进程加载file://协议；② iOS 模拟器加载http://localhost:5173；③ 真机通过 USB 网络共享访问。t3code 采用分环境代理策略：

• Electron 开发模式：Vite 的server.proxy配置反向代理到http://localhost:3000（后端服务）；
• iOS 模拟器：用ngrok生成临时域名（如https://abc123.ngrok.io），在WKWebView加载时传入；
• iOS 真机：开启 Mac 的 Internet Sharing，让 iPhone 连接 Mac 的 Wi-Fi，然后在Info.plist中添加NSAppTransportSecurity允许http://192.168.x.x:5173。

关键代码在packages/web/vite.config.ts：

export default defineConfig(({ command, mode }) => { const config: UserConfig = { server: { port: 5173, host: true, proxy: { '/api': { target: 'http://localhost:3000', changeOrigin: true, } } } }; if (mode === 'ios-dev') { // iOS 开发模式下，禁用 HMR，启用 https 代理 config.server.https = true; config.server.proxy = { '/api': { target: 'https://abc123.ngrok.io', changeOrigin: true, } }; } return config; });

提示：iOS 真机调试时，Safari 的 Web Inspector 是最强工具。在 iPhone 设置 > Safari > 高级 > 开启 Web Inspector，然后 Mac Safari > 开发 > [iPhone 名称] > [页面]，就能实时查看 DOM、Console、Network。我们曾用此方法发现一个 bug：iOS 16.4 的 WKWebView 在fetch()时默认不带Acceptheader，导致后端返回 HTML 而非 JSON，加一行headers: { Accept: 'application/json' }就解决。

3.7 步骤七：iOS 端 IPA 签名与 TestFlight 提交

t3code 的 iOS 构建产物是.xcarchive，需签名后才能安装。我们不用 Xcode GUI，而用命令行xcodebuild+altool流水线：

# 签名 xcodebuild -exportArchive \ -archivePath "./build/t3code.xcarchive" \ -exportPath "./build" \ -exportOptionsPlist "./scripts/exportOptions.plist" # 上传到 App Store Connect xcrun altool --upload-app \ -f "./build/t3code.ipa" \ -u "your@apple.com" \ -p "@keychain:APP_SPECIFIC_PASSWORD"

exportOptions.plist关键字段：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>method</key> <string>app-store</string> <key>teamID</key> <string>YOUR_TEAM_ID</string> <key>provisioningProfiles</key> <dict> <key>com.yourcompany.t3code</key> <string>YOUR_PROVISIONING_PROFILE_NAME</string> </dict> </dict> </plist>

注意：TestFlight 审核最常被拒的原因是“缺少隐私清单”（Privacy Manifest）。iOS 17+ 要求所有 App 在Info.plist中声明使用的隐私 API（如NSCameraUsageDescription）。t3code 的 Web 层若用navigator.mediaDevices.getUserMedia()，就必须在 iOS 工程的Info.plist中添加：

<key>NSCameraUsageDescription</key> <string>用于扫描模型二维码</string> <key>NSMicrophoneUsageDescription</key> <string>用于语音输入模型参数</string>

否则上传后 Apple 会自动拒绝，且不给具体错误码，只显示“Invalid Binary”。

4. 常见问题与实战排错指南：那些只有踩过坑才知道的细节

4.1 Electron 打包后 localhost 服务无法访问？检查防火墙与端口绑定

现象：开发时http://localhost:3000正常，打包成.app后，渲染进程 fetch 失败，报net::ERR_CONNECTION_REFUSED。

原因：Electron 打包后，主进程的 Node.js 服务默认只监听127.0.0.1，而渲染进程在file://协议下，Chrome 安全策略会阻止访问localhost（视为跨域）。解决方案是显式绑定0.0.0.0：

// electron/src/main.ts app.whenReady().then(() => { // 启动后端服务 const server = express(); server.listen(3000, '0.0.0.0'); // 关键：绑定 0.0.0.0，而非默认的 127.0.0.1 });

但这样做有安全风险，因此必须加一层校验：在server.use()中拦截非本地请求：

server.use((req, res, next) => { const ip = req.ip || req.connection.remoteAddress; if (ip !== '127.0.0.1' && !ip.startsWith('::ffff:127.0.0.1')) { return res.status(403).send('Forbidden'); } next(); });

实操心得：macOS 的防火墙有时会拦截0.0.0.0:3000，需在系统设置 > 防火墙 > 防火墙选项 > 勾选“允许已签名的应用程序接收传入连接”。我们曾遇到某客户 Mac 启用了防火墙，但没勾此项，导致打包版 App 无法联网，折腾了 2 小时才发现。

4.2 iOS 模拟器能加载，真机白屏？检查 ATS（App Transport Security）配置

现象：Xcode 运行模拟器正常，但用 USB 连接 iPhone 安装后，WKWebView 显示空白，Console 无报错。

原因：iOS 默认启用 ATS，强制 HTTPS，而开发时用的是http://localhost:5173。解决方案有两个：

• 临时方案：在Info.plist中禁用 ATS（仅限开发）：

<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict>

• 正式方案：用mkcert生成本地 HTTPS 证书，并在 Vite 中启用：

// web/vite.config.ts export default defineConfig({ server: { https: true, // 自动使用 mkcert 证书 } });

注意：NSAllowsArbitraryLoads在 App Store 审核中会被拒，必须在提交前删除。我们用构建脚本自动处理：scripts/prepare-for-appstore.js在打包前注入正式 plist，打包后还原开发 plist。

4.3 iOS 图标显示模糊？确认所有尺寸与 @2x/@3x 后缀

现象：App 安装后，Springboard 上图标边缘发虚，Spotlight 搜索结果图标缺失。

原因：Apple 要求图标必须精确匹配尺寸，且@2x图标必须是@1x的 2 倍像素，@3x是 3 倍。例如AppIcon60x60@2x.png必须是 120x120 像素，不能是 119x119。

验证方法：用iconutil命令行工具检查：

iconutil -c icns ./t3code/Assets.xcassets/AppIcon.appiconset/IconApp.iconset/ ls -la t3code.app/Contents/Resources/*.icns

如果输出中出现iconutil: Error reading icon set，说明某张图尺寸错误。

实操心得：我们写了个校验脚本scripts/validate-icons.js，遍历 xcassets 目录，用sharp库读取每张 PNG 的 actual size，对比 Apple 官方文档的尺寸表。曾发现设计师给的AppIcon20x20@3x.png实际是 59x59（应为 60x60），导致 iPhone SE 上图标缩放失真。

4.4 “model not found” 错误在 iOS 端频发？检查文件路径沙盒与权限

现象：Electron 版本能正常加载/Users/xxx/models/llama.bin，iOS 版本调用UIDocumentPickerViewController选中文件后，却报ERR_FILE_NOT_FOUND。

原因：iOS 文件路径是file:///var/mobile/Containers/Data/Application/.../Documents/llama.bin，但 WKWebView 的fetch()无法直接读取file://协议（沙盒限制）。必须由原生层读取后，转为blob:URL 或 Base64 传给 Web 层。

解决方案：在ViewController.swift中，读取文件后创建Blob：

func loadModel(payload: [String: Any]) { guard let filePath = payload["path"] as? String else { return } do { let data = try Data(contentsOf: URL(fileURLWithPath: filePath)) let base64 = data.base64EncodedString() // 传给 Web 层 webView.evaluateJavaScript("window.handleModelData('\(base64)')") } catch { sendResponse(to: webView, response: ["success": false, "error": error.localizedDescription]) } }

Web 层接收：

// web/src/services/modelService.ts (window as any).handleModelData = (base64: string) => { const arrayBuffer = Uint8Array.from(atob(base64), c => c.charCodeAt(0)).buffer; // 后续处理 arrayBuffer };

提示：大文件（>100MB）不能用 Base64，会 OOM。此时改用WKWebView的loadHTMLString动态注入<script>标签，或用NSURLSession下载到临时目录，再生成blob:URL。

4.5 Electron 打包 APK？澄清误区与可行路径

热搜词里有 “electron打包apk”，这其实是常见误解。Electron 本身不支持 Android，但 t3code 可延伸支持 Android，路径如下：

• 方案 A（推荐）：用 Capacitor 封装 Web 层，复用packages/web/dist/，通过Capacitor Plugins调用 Android 原生 API；
• 方案 B（兼容旧项目）：用 Electron + Cordova 混合，但 Cordova 的 WebView 已过时，不推荐；
• 方案 C（未来方向）：等待 Electron 官方的 Android 支持（目前处于实验阶段，不建议生产使用）。

我们实测 Capacitor 方案：npx cap add android后，只需在android/app/src/main/res/xml/config.xml中配置：

<feature name="FileSystem"> <param name="android-package" value="capacitor.plugins.filesystem.FileSystemPlugin" /> </feature>

然后 Web 层调用Capacitor.Plugins.FileSystem.readFile()，与 iOS 的UIDocumentPicker逻辑一致。

注意：Capacitor 的 Android 构建需 JDK 17+ 和 Android SDK 33+，且必须在android/app/build.gradle中启用android.useAndroidX=true。我们曾因 JDK