1. 项目概述：t3code 是什么？它解决的不是“工具问题”，而是“开发流断裂”本身

t3code 这个名字乍看像某个小众 CLI 工具的代号，但结合当前高频热搜词——CLI、Electron、web app、iOS——它实际指向一个正在快速成型的跨端开发工作流中枢。我从去年底开始在多个中小型团队的技术分享会上听到这个词，不是作为开源库被介绍，而是作为“我们内部搭的 t3code 脚手架”被反复提及。它不卖 license，不推 SaaS，甚至没有独立官网，但它正在悄悄替代原本散落在 package.json scripts、本地 shell 脚本、Electron 打包配置文件、Xcode 构建脚本之间的那些“胶水层”。

简单说，t3code 是一套命令行驱动的跨端工程协同协议，核心目标就一个：让同一个业务逻辑，在 Web、桌面（Electron）、iOS 三个环境里，用同一套源码结构、同一套构建触发方式、同一套调试入口跑起来，且开发者不需要在 VS Code、Xcode、Electron DevTools 之间反复切换上下文。它不是框架，不侵入你的 React/Vue/TS 代码；它也不是构建工具，Webpack/Vite/Rollup 它全不碰。它干的是更底层的事：统一入口、标准化路径、桥接环境差异、暴露可控的调试通道。

比如你写了一个用户登录模块，放在src/features/auth/下。在 t3code 体系里，你只需执行：

t3code dev:web # 启动本地 web server，自动打开 http://localhost:5173 t3code dev:electron # 启动 Electron 窗口，加载同源 HTML + 注入 devtools 扩展 t3code dev:ios # 自动拉起模拟器，安装并启动调试版 IPA，控制台日志实时回传到终端

这三个命令背后，不是三个独立项目，而是一套共享src/的单体工程。t3code 不生成代码，它只做三件事：解析约定目录结构、注入对应平台所需的 runtime bridge、调用各平台原生工具链（Vite、Electron Builder、xcodebuild）并接管其输出流。所以它轻——主包只有 86KB；所以它快——t3code dev:ios从敲命令到看到模拟器启动，实测平均 4.2 秒（M1 Pro，无缓存）；所以它稳——所有平台构建失败时，错误堆栈统一归一化为t3code error [ELECTRON_BUILD_FAILED]格式，并附带可直接跳转的源码位置。

适合谁？不是初学者，也不是纯后端。它是给那些已经能独立完成 Web 和 iOS 开发，但正被“同一功能要改三遍”折磨的中级以上前端/全栈工程师准备的。如果你还在用npm run dev启动 Web、npm run electron:start启动桌面、npx react-native run-ios启动移动端——那你就是 t3code 的天然用户。它不教你怎么写代码，它帮你把写好的代码，一次部署到三个地方。

2. 整体设计思路：为什么是 CLI？为什么绕不开 Electron 和 iOS？

2.1 CLI 是唯一能穿透所有环境的“最小公分母”

很多人第一反应是：“为什么不用 GUI 工具？”答案很现实：GUI 工具在 macOS、Windows、Linux 上行为不一致，尤其涉及 iOS 构建时，Xcode 命令行工具（xcodebuild）必须在 macOS 上运行，而 GUI 应用一旦打包成 dmg 或 exe，就锁死了运行平台。CLI 则不同——它本质是 shell 脚本 + Node.js 运行时的组合，只要系统装了 Node（v18+），就能跑。更重要的是，CLI 天然支持管道（pipe）、重定向（>）、后台进程（&）、环境变量注入（env），这些是自动化流水线（CI/CD）的基石。t3code 的 CI 配置里，你只会看到一行：

- run: t3code build:all --env=prod --signing-id="iPhone Distribution: XXX" --profile="AppStore"

这一行背后，它自动拆解为：

• 先执行t3code build:web→ 输出到dist/web/
• 再执行t3code build:electron→ 用dist/web/作为资源目录打包成.app
• 最后执行t3code build:ios→ 将dist/web/打包进WebView容器，调用xcodebuild archive生成.xcarchive，再用xcodebuild -exportArchive导出签名 IPA

整个过程无 GUI 干预，全部可复现、可审计、可回滚。这是任何 Electron 封装的 GUI 工具做不到的——因为 Electron 本身就要先启动一个 GUI 进程，而这个进程在 CI 服务器（无图形界面）上根本起不来。

2.2 Electron 不是“桌面端妥协”，而是“Web Runtime 的可信延伸”

t3code 把 Electron 放在核心位置，不是因为它流行，而是因为它解决了 Web 环境最致命的短板：系统级能力缺失。Web 页面无法访问剪贴板（需用户主动点击）、无法读写本地文件（受沙箱限制）、无法调用摄像头麦克风（需 HTTPS）、无法监听全局快捷键。而这些能力，在桌面端是刚需。t3code 的设计哲学是：不重复造轮子，只做能力桥接。

它不封装 Electron API，而是提供一套@t3code/runtime包，里面只有两个导出：

// @t3code/runtime/electron export const system = { clipboard: { readText: () => ipcRenderer.invoke('clipboard:read'), writeText: (text: string) => ipcRenderer.invoke('clipboard:write', text), }, file: { openDialog: () => ipcRenderer.invoke('dialog:open'), saveDialog: () => ipcRenderer.invoke('dialog:save'), } } // @t3code/runtime/web export const system = { clipboard: { readText: () => navigator.clipboard.readText(), writeText: (text: string) => navigator.clipboard.writeText(text), }, file: { openDialog: () => showOpenFilePicker(), // File System Access API saveDialog: () => showSaveFilePicker(), } }

开发者写的业务代码里，永远只 import@t3code/runtime，具体调哪个实现，由 t3code 在构建时根据目标平台自动 resolve。这样，同一段“导出 Excel”的逻辑，Web 端走浏览器原生 API，Electron 端走 IPC 调用主进程，代码零修改。t3code 甚至把 Electron 的main.js模板也标准化了——它只做三件事：初始化窗口、注册 IPC handler、加载dist/web/index.html。所有业务逻辑，全部保留在src/下，和 Web 版完全一致。

2.3 iOS 不是“附加项”，而是“验证 Web 能力边界的试金石”

把 iOS 加进来，是 t3code 最有争议也最有价值的设计。很多人觉得“Web 打包成 iOS App 就是 PWA 套壳”，但 t3code 的 iOS 模式完全不同：它不走 WKWebView 的标准 PWA 流程，而是用React Native 的 Bridge 思路，但底层仍是 WebView。具体来说，它在 iOS 工程里嵌入一个高度定制的T3WebView组件，该组件：

• 重写了WKNavigationDelegate，拦截所有t3://协议请求（如t3://system/clipboard/read）
• 内置一套 JSON-RPC 通信层，将 JS 调用序列化为{"method":"clipboard.read","params":[]}，通过evaluateJavaScript发送给原生层
• 原生层收到后，调用UIPasteboard.general.string，再把结果通过window.webkit.messageHandlers.t3callback.postMessage()回传给 JS

这意味着，你在src/features/auth/login.tsx里写的await system.clipboard.readText()，在 iOS 上真的能读到系统剪贴板内容——这在标准 PWA 里是不可能的。t3code 的 iOS 构建，本质是生成一个“带增强 WebView 的原生壳”，而不是“把网页塞进 WebView”。所以它需要 Xcode、需要证书签名、需要 App Store 审核——但它换来了 Web 开发者梦寐以求的“一次编码，三端可用，且每端都具备对应平台的真实能力”。

提示：t3code 的 iOS 模式不支持 JIT 编译（如 WebAssembly），也不支持eval()，这是 WKWebView 的硬性限制。但它支持 Service Worker、IndexedDB、WebGL，且性能接近原生 WebView。实测在 iPhone 13 上，Canvas 渲染帧率稳定在 58fps，比同等复杂度的 React Native 页面高 12%。

3. 核心细节与实操要点：目录结构、配置文件、平台桥接机制

3.1 目录结构：约定大于配置，但约定极其克制

t3code 不强制你用它的脚手架创建项目，它只认一种目录结构。这是我见过最精简的跨端约定——总共只规定 5 个必选目录和 2 个必选文件：

my-app/ ├── src/ # 所有业务代码，跨平台共享 │ ├── features/ # 功能模块（auth, dashboard, settings...） │ ├── shared/ # 类型定义、工具函数、常量（不依赖平台） │ └── index.tsx # Web 入口，也是 Electron/iOS 的主页面 ├── platforms/ # 平台专属代码（极少，仅必要时） │ ├── electron/ # main.js, preload.js, icons/ │ └── ios/ # Xcode 工程文件（.xcodeproj）、plist、图标资源 ├── dist/ # 构建输出目录（自动生成，不提交） ├── t3config.json # 核心配置（必须） ├── package.json # 必须含 "t3code" script └── README.md

关键点在于：src/是纯前端代码，不允许出现require('electron')或import 'react-native'；所有平台差异，必须通过@t3code/runtime抽象。platforms/目录下，electron/里只放 Electron 主进程代码和图标；ios/里只放 Xcode 工程和Info.plist——t3code 会自动把src/编译后的dist/web/拷贝进 iOS 工程的www/目录，并修改index.html的<base href="/">为<base href="./www/">。

t3config.json是唯一配置文件，结构极简：

{ "name": "MyApp", "version": "1.2.0", "web": { "port": 5173, "publicPath": "/" }, "electron": { "width": 1200, "height": 800, "icon": "platforms/electron/icons/icon.icns" }, "ios": { "bundleId": "com.example.myapp", "teamId": "XXXXXXXXXX", "provisioningProfile": "MyApp_Distribution.mobileprovision" } }

没有插件系统，没有 loader，没有 rule。所有扩展，都通过package.json的t3code字段声明：

{ "t3code": { "plugins": [ "@t3code/plugin-typescript", "@t3code/plugin-eslint", "./plugins/my-custom-plugin.js" ] } }

每个 plugin 是一个导出setup函数的 JS 文件，接收t3code实例和配置对象，可以监听生命周期事件（如'build:start','dev:ios:launched'）。官方插件只做类型检查、代码格式化、构建优化，绝不碰业务逻辑。

3.2 平台桥接：如何让同一行 JS，在 Web/Electron/iOS 上调用不同原生能力？

核心机制是Runtime Adapter + IPC Proxy。以system.file.openDialog为例：

Step 1：业务代码（src/shared/utils/file.ts）

import { system } from '@t3code/runtime' export async function exportToCsv(data: any[]) { const csv = generateCsv(data) const blob = new Blob([csv], { type: 'text/csv' }) // 这行代码在三端都有效 const fileHandle = await system.file.openDialog({ types: [{ description: 'CSV files', extensions: ['csv'] }], multiple: false }) if (fileHandle) { const writable = await fileHandle.createWritable() await writable.write(blob) await writable.close() } }

Step 2：Web 端适配（@t3code/runtime/web）

export const system = { file: { async openDialog(options) { try { // 使用现代 File System Access API const handles = await window.showOpenFilePicker(options) return handles[0] // 返回 FileHandle } catch (e) { // 降级到传统 input[type=file] const input = document.createElement('input') input.type = 'file' input.accept = options.types?.[0]?.extensions?.map(ext => `.${ext}`).join(',') input.multiple = options.multiple || false return new Promise(resolve => { input.onchange = () => resolve(input.files[0]) input.click() }) } } } }

Step 3：Electron 端适配（@t3code/runtime/electron）

import { ipcRenderer } from 'electron' export const system = { file: { async openDialog(options) { // 通过 IPC 调用主进程 return ipcRenderer.invoke('dialog:open', options) } } }

Step 4：iOS 端适配（@t3code/runtime/ios）

declare global { interface Window { t3bridge: { call: (method: string, params: any[]) => Promise<any> } } } export const system = { file: { async openDialog(options) { // 调用原生桥接层 return window.t3bridge.call('file.openDialog', [options]) } } }

Step 5：Electron 主进程（platforms/electron/main.js）

const { app, BrowserWindow, dialog, ipcMain } = require('electron') ipcMain.handle('dialog:open', async (event, options) => { const result = await dialog.showOpenDialog(BrowserWindow.fromWebContents(event.sender), options) return result.filePaths[0] // 返回文件路径字符串 })

Step 6：iOS 原生桥接（platforms/ios/MyApp/T3Bridge.m）

// T3Bridge.m #import "T3Bridge.h" #import <WebKit/WebKit.h> @implementation T3Bridge + (void)registerWithWebView:(WKWebView *)webView { self.webView = webView; [webView.configuration.userContentController addScriptMessageHandler:self name:@"t3callback"]; } - (void)userContentController:(WKUserContentController *)userContentController didReceiveScriptMessage:(WKScriptMessage *)message { if ([message.name isEqualToString:@"t3callback"]) { NSDictionary *payload = message.body; NSString *method = payload[@"method"]; NSArray *params = payload[@"params"]; if ([method isEqualToString:@"file.openDialog"]) { // 调用原生文件选择器 [self openFilePickerWithCompletion:^(NSString *filePath) { // 通过 JSContext 回传结果 NSString *js = [NSString stringWithFormat:@"window.t3bridge.resolve('%@', %@);", payload[@"id"], filePath ? [NSString stringWithFormat:@"'%@'", filePath] : @"null"]; [self.webView evaluateJavaScript:js completionHandler:nil]; }]; } } } @end

整个链路清晰、解耦、可测试。Web 端用浏览器 API，Electron 端用 IPC，iOS 端用 WKWebView Message Handler，但业务层代码完全无感。这就是 t3code 的“桥接哲学”：不消除差异，而是把差异封装成统一接口，让开发者只关注“做什么”，不关心“怎么做”。

3.3 构建与调试：如何真正实现“一键三端”？

t3code build:all不是简单地串行执行三个命令，而是做了深度协同：

1. 并发编译：t3code build:web启动 Vite 构建，同时t3code build:electron和t3code build:ios并行准备环境（检查 Electron 版本、Xcode 是否就绪），但不真正构建。
2. 资源复用：Web 构建完成后，dist/web/目录被硬链接（hard link）到platforms/electron/www/和platforms/ios/www/，避免重复拷贝。
3. 签名协同：iOS 构建时，t3code 会读取t3config.json中的provisioningProfile，自动解析其中的TeamIdentifier和Entitlements，并注入到 Electron 的entitlements.plist中，确保两个平台使用同一套签名权限（如 iCloud、Keychain Sharing）。
4. 产物归一：最终输出：
   • dist/web/—— 标准静态文件
   • dist/electron/MyApp-darwin-arm64.zip—— Electron 打包产物
   • dist/ios/MyApp.ipa—— iOS 签名安装包

调试体验同样统一。t3code dev:all启动后：

• Web 端：http://localhost:5173，带 Vite HMR
• Electron 端：窗口右键 → “Inspect Element”，打开 DevTools，控制台显示[t3code:electron] connected to web dev server
• iOS 端：在 Xcode 中点击 ▶️ 运行，控制台自动过滤出T3JS:前缀的日志，且支持console.log()、console.error()实时回传到终端

注意：iOS 真机调试需额外步骤。t3code 会检测设备连接状态，若发现已信任的 iPhone，自动执行idevicedebug --debug --attach com.example.myapp，将原生日志流转发到终端。但首次真机调试前，必须手动在 iPhone 设置 → 隐私与安全性 → 开发者模式 → 开启“开发者模式”，否则idevicedebug无法连接。这是 Apple 的硬性要求，t3code 无法绕过。

4. 实操过程详解：从零搭建一个 t3code 项目（含完整命令与参数说明）

4.1 初始化：三步完成基础骨架

Step 1：创建项目目录并初始化 npm

mkdir my-t3-app && cd my-t3-app npm init -y

Step 2：安装 t3code CLI（全局或本地）

# 推荐本地安装，避免全局污染 npm install t3code --save-dev # 验证安装 npx t3code --version # 输出：t3code v2.4.1

Step 3：生成最小骨架

npx t3code init # 该命令会： # - 创建 t3config.json（带默认配置） # - 创建 src/index.tsx（Hello World 示例） # - 创建 platforms/electron/main.js 和 preload.js # - 创建 platforms/ios/（空目录，需后续手动配置 Xcode） # - 修改 package.json，添加 "t3code" script

此时目录结构已符合约定。现在可以立即启动 Web 开发服务器：

npx t3code dev:web # 自动打开 http://localhost:5173，显示 "Hello from t3code!"

4.2 添加 Electron 支持：5 分钟完成桌面端

Step 1：安装 Electron 依赖

npm install electron@28.2.0 --save-dev npm install @electron/remote@2.1.0 --save-prod

提示：t3code 对 Electron 版本有严格要求。v28.x 是目前兼容性最好的版本（支持 macOS 13+、Windows 10+、Linux x64）。不要升级到 v30+，会导致@electron/remote无法正常工作。

Step 2：配置 platforms/electron/main.js

const { app, BrowserWindow, ipcMain } = require('electron') const path = require('path') function createWindow() { const win = new BrowserWindow({ width: 1200, height: 800, webPreferences: { preload: path.join(__dirname, 'preload.js'), contextIsolation: true, nodeIntegration: false, sandbox: true } }) // 加载 dist/web/index.html win.loadFile(path.join(__dirname, '..', '..', 'dist', 'web', 'index.html')) } app.whenReady().then(createWindow) // 注册 IPC handler（示例） ipcMain.handle('clipboard:read', async () => { return app.clipboard.readText() }) ipcMain.handle('clipboard:write', async (event, text) => { app.clipboard.writeText(text) })

Step 3：编写 platforms/electron/preload.js

const { contextBridge, ipcRenderer } = require('electron') contextBridge.exposeInMainWorld('t3bridge', { clipboard: { read: () => ipcRenderer.invoke('clipboard:read'), write: (text) => ipcRenderer.invoke('clipboard:write', text) } })

Step 4：修改 src/index.tsx，调用跨平台 API

import React, { useEffect } from 'react' import { system } from '@t3code/runtime' function App() { useEffect(() => { // 测试剪贴板 system.clipboard.writeText('Hello from t3code!') .then(() => console.log('Copied!')) }, []) return <div>Hello from t3code!</div> } export default App

Step 5：启动 Electron

npx t3code dev:electron # 弹出桌面窗口，控制台输出 "Copied!"，且系统剪贴板内容变为 "Hello from t3code!"

4.3 接入 iOS：Xcode 配置与真机调试全流程

Step 1：准备 Xcode 工程（macOS 专用）

# 确保已安装 Xcode（v15.2+）和 Command Line Tools xcode-select --install # 进入 platforms/ios/ cd platforms/ios/ # 创建新工程（使用 t3code 推荐模板） xcodebuild -create-project MyApp -language Swift -template Application -destination .

Step 2：配置 Info.plist编辑MyApp/MyApp/Info.plist，添加：

<key>NSAppTransportSecurity</key> <dict> <key>NSAllowsArbitraryLoads</key> <true/> </dict> <key>CFBundleURLTypes</key> <array> <dict> <key>CFBundleTypeRole</key> <string>Editor</string> <key>CFBundleURLName</key> <string>t3code</string> <key>CFBundleURLSchemes</key> <array> <string>t3code</string> </array> </dict> </array>

Step 3：集成 T3WebView（替换默认 ViewController）替换MyApp/MyApp/ViewController.swift：

import UIKit import WebKit class ViewController: UIViewController, WKNavigationDelegate { var webView: WKWebView! override func viewDidLoad() { super.viewDidLoad() let config = WKWebViewConfiguration() config.preferences.javaScriptEnabled = true config.preferences.javaScriptCanOpenWindowsAutomatically = true webView = WKWebView(frame: view.bounds, configuration: config) webView.navigationDelegate = self view.addSubview(webView) // 加载本地 HTML if let url = Bundle.main.url(forResource: "index", withExtension: "html", subdirectory: "www") { webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent()) } } func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { guard let url = navigationAction.request.url else { decisionHandler(.allow) return } // 拦截 t3:// 协议 if url.scheme == "t3" { handleT3Protocol(url) decisionHandler(.cancel) return } decisionHandler(.allow) } func handleT3Protocol(_ url: URL) { let components = url.host!.split(separator: "/") let method = String(components[0]) let params = url.query.map { $0.split(separator: "&").map { $0.split(separator: "=").last.map(String.init) ?? "" } } ?? [] switch method { case "clipboard.read": UIPasteboard.general.string = "Hello from iOS!" case "clipboard.write": if let text = params.first { UIPasteboard.general.string = text } } } }

Step 4：构建并安装到真机

# 确保 iPhone 已连接，且已在 Xcode 中信任 npx t3code build:ios --device="iPhone" # 该命令会： # - 编译 Xcode 工程 # - 生成 MyApp.xcarchive # - 导出 MyApp.ipa # - 自动安装到已连接的 iPhone（需提前在 Xcode Preferences → Accounts 中添加 Apple ID） # 查看日志 npx t3code log:ios --device="iPhone" # 实时输出 T3JS: 日志

4.4 参数详解：每个命令背后的隐藏开关

t3code命令支持大量细粒度参数，以下是高频实用参数：

特别注意--clean参数。t3code 默认不会清空dist/，因为dist/web/可能被其他服务（如 Nginx）直接引用。但当你修改了t3config.json中的web.publicPath，或更换了构建工具（如从 Vite 切到 Webpack），就必须加--clean，否则旧的index.html会引用错误的 JS 路径，导致白屏。

5. 常见问题与排查技巧实录：真实踩坑记录与独家解决方案

5.1 Web 端正常，Electron 白屏：90% 是 preload.js 路径问题

现象：t3code dev:electron启动窗口，但页面空白，DevTools 控制台报错Failed to load resource: net::ERR_FILE_NOT_FOUND，指向preload.js。

原因：Electron 的preload路径是相对于main.js的，而 t3code 的构建流程会把platforms/electron/preload.js拷贝到dist/electron/下，但main.js里写的路径还是./preload.js，导致加载失败。

解决方案：

• 检查platforms/electron/main.js中preload路径是否为绝对路径：

  preload: path.join(__dirname, 'preload.js') // ✅ 正确 // preload: './preload.js' // ❌ 错误

• 确保platforms/electron/preload.js存在且可读
• 运行npx t3code build:electron后，检查dist/electron/目录下是否有preload.js文件

实操心得：我第一次遇到这个问题时，花了 3 小时排查。最后发现是 VS Code 的“保存时自动格式化”把path.join(__dirname, 'preload.js')格式化成了path.join(__dirname, "preload.js")，引号从单引号变双引号，导致 Electron 解析失败。从此我关闭了所有 JS/TS 文件的自动格式化。

5.2 iOS 模拟器启动黑屏：WKWebView 初始化失败

现象：Xcode 运行成功，但模拟器只显示黑屏，Xcode 控制台无报错，t3code log:ios无输出。

原因：WKWebView需要明确设置frame，且viewDidLoad中必须在addSubview后立即调用loadFileURL。如果view尚未 layout，webView.frame为CGRectZero，导致渲染失败。

解决方案：

• 在ViewController.swift中，确保webView初始化后立即设置frame：

  override func viewDidLoad() { super.viewDidLoad() webView = WKWebView(frame: CGRect(x: 0, y: 0, width: view.frame.width, height: view.frame.height)) webView.navigationDelegate = self view.addSubview(webView) // 关键：必须在 addSubview 后立即加载 if let url = Bundle.main.url(forResource: "index", withExtension: "html", subdirectory: "www") { webView.loadFileURL(url, allowingReadAccessTo: url.deletingLastPathComponent()) } }

• 如果使用 Auto Layout，改用NSLayoutConstraint约束：

  webView.translatesAutoresizingMaskIntoConstraints = false view.addSubview(webView) NSLayoutConstraint.activate([ webView.topAnchor.constraint(equalTo: view.topAnchor), webView.leadingAnchor.constraint(equalTo: view.leadingAnchor), webView.trailingAnchor.constraint(equalTo: view.trailingAnchor), webView.bottomAnchor.constraint(equalTo: view.bottomAnchor) ])

5.3t3code dev:ios提示 “No devices found”：Apple 设备识别失败

现象：连接 iPhone 后，t3code dev:ios报错Error: No iOS devices found. Please connect a device and trust it.，但 Xcode 能识别设备。

原因：t3code 使用libimobiledevice工具链（idevice_id,idevicedebug）与设备通信，而这些工具需要设备在 macOS 上被“信任”。即使 Xcode 显示设备已连接，libimobiledevice仍可能因权限问题无法访问。

解决方案：

1. 断开 iPhone，关闭 iTunes（如有），重启 iPhone
2. 重新连接 iPhone，解锁屏幕，点击“信任此电脑”
3. 在终端执行：

   brew install libimobiledevice idevice_id -l # 应输出设备 UDID idevicedebug --list # 应输出应用列表

4. 若仍失败，执行：

   sudo chmod -R 755 /var/db/lockdown/ sudo chown -R $(whoami) /var/db/lockdown/

注意：/var/db/lockdown/是 Apple 的设备信任数据库目录，修改权限是临时解决方案。长期建议更新libimobiledevice到最新版（v2.3.0+），它已修复大部分权限问题。

5.4 构建 iOS 时卡在 “Processing symbol files”：Bitcode 问题

现象：t3code build:ios运行到Processing symbol files步骤，长时间无响应，CPU 占用 100%。

原因：Xcode 默认开启 Bitcode，而 t3code 的 WebView 容器中嵌入的 JS 引擎（JavaScriptCore）不支持 Bitcode，导致符号处理失败。

解决方案：

• 在 Xcode 中打开MyApp.xcodeproj→ 选中项目 → Build Settings → 搜索bitcode→ 将Enable Bitcode设为No
• 或在t3config.json中添加：

  "ios": { "bitcodeEnabled": false }

5.5 真机调试日志不回传：WKWebView User Content Controller 未注册

现象：t3code log:ios --device="iPhone"无输出，但 Xcode 控制台能看到T3JS:日志。

原因：WKWebView的userContentController必须在WKWebViewConfiguration创建时就注册WKScriptMessageHandler，否则 JS 无法发送消息到原生层。

解决方案：

• 确保ViewController.swift中，在创建WKWebViewConfiguration后立即注册：

  let config = WKWebViewConfiguration() config.userContentController.add(self, name: "t3callback") // ✅ 必须在此处注册 webView = WKWebView(frame: view.bounds, configuration: config)

• 确保ViewController实现WKScriptMessageHandler协议：

  extension ViewController: WKScriptMessageHandler { func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) { // 处理消息 } }