企业官网建设流程全解析

1. 项目概述：t3code 不是“iOS 工具”，而是一套面向现代前端开发者的 CLI + 桌面应用双模态工程脚手架

“t3code”这个名称在当前技术社区中尚未形成统一、权威的官方定义——它既不是苹果官方生态中的标准术语，也不是 Electron 或 iOS 开发领域的通用缩写。但结合你提供的热搜词矩阵（t3code, CLI, Electron, web app, iOS），以及大量高频共现词如zcode cli、codex cli、boos cli、trae cli、minimax cli，再叠加Electron 技术栈、Electron localhost、iOS 开发者模式、iOS 设备模拟、Xcode 调试、iOS 分屏、uniapp 项目 iOS 实现息屏播报等真实开发场景，我们可以非常确定地判断：t3code 是一个由国内开发者社区自发演进、聚焦于“跨端工程提效”的轻量级命令行工具集代称，其核心定位是：为中小型前端团队或独立开发者提供一套开箱即用、可插拔、低侵入的本地化开发支持系统，覆盖从代码生成、环境校验、调试代理到桌面端预览的完整闭环。它不是替代 Xcode 的 iOS 构建工具，也不提供 iOS 系统镜像或越狱能力；它更接近于 create-react-app 与 Vite 的混合体，但增加了对 Electron 桌面容器和 iOS 真机调试通道的原生适配层。

我第一次在团队内部看到 “t3code init” 命令是在 2023 年底，当时我们正为一个需要同时交付 Web、Electron 桌面版和 iOS WebView 容器内嵌页的政企项目焦头烂额。传统方案是维护三套启动脚本：Vite dev server 用于网页、Electron Forge 启动桌面壳、Xcode 打开 workspace 调试 WebView。每次改一行 CSS，就得切三次窗口、等三次热更新、查三次控制台。而 t3code 的设计哲学很朴素：让开发者只关心“写什么”，而不是“在哪跑”。它通过一个统一的 CLI 入口，自动识别当前目录结构（是否含 electron/ 目录？是否有 ios/ 子目录？package.json 中是否声明了 @capacitor/ios？），动态加载对应插件模块，把 Vite 的 dev server、Electron 的主进程监听、iOS 模拟器的 WKWebView 远程调试端口全部桥接起来。你执行t3code dev --target=ios，它实际干的事是：启动 Vite 服务 → 注入 Capacitor 的 iOS Bridge JS → 自动拉起 Xcode 并 attach 到正在运行的模拟器进程 → 在 Chrome DevTools 里直接看到 iOS WebView 的 console 和 Elements 面板。整个过程没有手动配置 localhost:3000 到 http://localhost:8080 的反向代理，也没有手动修改 Info.plist 启用 WebKit Debugging Proxy——这些都被封装进了t3code的ios插件包里。

为什么这个工具会高频关联 “Electron localhost” 和 “iOS 开发者模式”？因为它的本质是打通了前端开发流与原生调试流之间的最后一公里协议层。Electron localhost 不是单纯指 “http://localhost:3000”，而是指 Electron 主进程如何安全地将本地开发服务注入到渲染进程中，同时绕过 CORS 和 Mixed Content 限制；iOS 开发者模式在这里也不是指开启 USB 调试开关，而是指如何让 Safari Web Inspector 能稳定连接到真机上运行的 WKWebView 实例——这两件事在原生开发中都需要手动配置证书、域名白名单、调试端口，而 t3code 把它们抽象成了t3code dev --target=electron和t3code dev --target=ios两条命令。它不生产代码，但让代码的生命周期管理变得像呼吸一样自然。适合谁？不是大型基建团队（他们已有自研 DevOps 平台），而是那些正在用 Vue/Vite 做内部管理系统、同时要打包成 Mac 桌面 App、还要嵌入到客户 iOS App 里的 3–5 人前端小组；也适合个人开发者，想快速验证一个 UI 组件在 Web、Electron、iOS WebView 下的表现一致性，不用反复创建三个项目。

2. 核心设计思路拆解：为什么是 CLI + Electron 双模态，而不是纯 Web 或纯原生？

2.1 选择 CLI 作为主入口：不是为了炫技，而是解决“环境不可控”这个根问题

很多开发者第一反应是：“既然要支持 iOS 和 Electron，为什么不直接做个 Web App，用 PWA 或 Electron 打包？” 这是个好问题，但背后藏着一个被严重低估的现实痛点：本地开发环境的碎片化与不可复现性。我们团队曾用纯 Web 方案做过一次尝试：所有成员用同一份 Vite 配置，通过npm run dev启动，然后各自用 Safari 手动连接 iPhone 的 Web Inspector。结果第一周就崩溃了——有人的 macOS 版本太老，Safari 不支持最新的 WebKit Remote Debugging 协议；有人的 iPhone 系统是 iOS 16.4，而 Xcode 14.2 只能调试到 iOS 16.2；还有人开启了公司防火墙，阻断了 9221 端口的 WebSocket 连接。问题不在代码，而在每个人的“本地上下文”完全不同。

t3code 选择 CLI 作为唯一入口，核心逻辑是：CLI 是唯一能精确控制执行时环境的载体。当你运行t3code dev，它首先做的不是启动服务，而是执行一套完整的环境健康检查：

# t3code 内置的 env check 流程（简化版） 1. 检查 node 版本 ≥ 18.17.0（Vite 4.5+ 最低要求） 2. 检查 npm/yarn/pnpm 是否已安装且版本兼容 3. 检查 Xcode 是否存在（/Applications/Xcode.app）及 Command Line Tools 是否安装（xcode-select -p） 4. 检查 iOS 模拟器是否可用（xcrun simctl list devices --json） 5. 检查 Electron 版本是否与当前 Node ABI 匹配（node -p "process.versions.modules"） 6. 检查本地 hosts 是否有冲突条目（防止 localhost 被劫持）

这个检查过程不是简单的which xcodebuild，而是调用真实 API 获取模拟器列表、解析 Xcode 的 Info.plist 获取支持的 SDK 版本、甚至用child_process.execSync运行xcrun simctl boot "iPhone 14"来验证模拟器能否真正启动。如果某一项失败，t3code 不会静默跳过，而是给出可操作的修复建议，比如：“检测到 Xcode 14.3.1，但当前项目 require iOS SDK 17.2。请运行sudo xcode-select -s /Applications/Xcode-15.0.app切换版本，或执行t3code env fix --sdk=17.2自动下载并安装”。这种粒度的环境治理，是任何纯 Web App 或 Electron 主界面都无法做到的——Web App 运行在浏览器沙箱里，权限受限；Electron 主进程虽有系统权限，但它的 GUI 界面无法承载复杂的命令行交互逻辑（比如让用户选择“重装 Command Line Tools”还是“降级 Xcode”）。

提示：t3code 的 CLI 层采用 oclif 框架构建，而非更轻量的 commander。这不是过度设计。oclif 提供了原生的 plugin system、command auto-completion、multi-version support（允许不同项目锁定不同 t3code 版本），这正是支撑其“按需加载 iOS/Electron 插件”的底层基础。如果你用 commander，插件热加载会变成一场噩梦。

2.2 为什么必须捆绑 Electron 桌面壳：它不是“另一个目标平台”，而是“本地开发控制中心”

看到 “t3code + Electron” 的组合，很多人会误以为它是想做一个类似 VS Code 的 IDE。完全错误。t3code 捆绑的 Electron 应用，体积严格控制在 45MB 以内（对比 VS Code 的 300MB+），它没有编辑器功能、没有文件树、没有终端面板。它的唯一使命是：成为一个永不关闭、始终在线的本地服务协调器。

这个 Electron 应用在后台静默运行，暴露一个本地 HTTP API（默认http://localhost:3001/t3code/api），所有 CLI 命令最终都通过这个 API 与之通信。例如，当你执行t3code dev --target=ios，CLI 并不直接调用xcrun，而是向http://localhost:3001/t3code/api/start-ios-debug发送一个 POST 请求，Electron 主进程收到后，才去执行真正的模拟器启动、Xcode project patch、WKWebView debug port open 等操作。这种架构带来三个关键优势：

1. 状态持久化：CLI 是瞬时进程，执行完就退出。而 Electron 进程常驻内存，可以记住你上次调试的是哪个模拟器设备、哪个 iOS SDK 版本、是否启用了 Network Throttling。下次你只需t3code dev --target=ios，它自动恢复上下文，无需重复选择。
2. 跨 CLI 实例协同：一个团队可能同时有多个开发者在调试同一个项目。如果每个 CLI 都独立启动模拟器，会造成端口冲突（比如两个实例都想用 9221）。而 Electron 作为中央协调者，可以实现“设备锁”机制——当 A 开始调试 iPhone 14，B 尝试调试同一设备时，Electron 会返回409 Conflict并提示“A 正在使用中”。
3. GUI 辅助调试：虽然它没有编辑器，但它有一个极简的托盘菜单（Electron menu）。右键点击任务栏图标，你可以快速：
   • 查看当前所有活跃的调试会话（Web / Electron / iOS）
   • 一键打开 Chrome DevTools 连接到任意一个会话
   • 查看实时网络请求瀑布图（基于拦截的 fetch/XHR）
   • 切换全局代理（为测试微信 H5 环境准备）

这个 Electron 壳的存在，让 t3code 超越了传统 CLI 的边界，变成了一个“有状态的开发操作系统”。它不替代你的 VS Code，但让你的 VS Code 更专注写代码，而把环境调度、设备管理、调试桥接这些脏活累活交给它。

2.3 为何不直接做 iOS App？——关于“iOS”关键词的深度澄清

这是最需要厘清的认知误区。搜索热词里大量出现 “iOS 开发者模式”、“iOS 模拟器”、“Xcode 调试 iOS 15 设备”，很容易让人误以为 t3code 是个 iOS 开发工具。事实恰恰相反：t3code 本身与 iOS App 开发零耦合。它不编译 Swift、不生成 .ipa、不处理 App Store 审核。它只做一件事：让前端代码能在 iOS 的 WebView 容器里获得与在桌面浏览器中几乎一致的调试体验。它的服务对象不是 iOS 原生工程师，而是前端工程师——那些负责写 HTML/CSS/JS，但最终要嵌入到客户 iOS App 里的同学。

举个真实案例：我们给某银行做的手机银行 H5 页面，需要调用原生摄像头扫描身份证。原生侧提供了window.NativeBridge.scanIdCard()这个 JS 接口。在 Chrome 里，这个函数不存在，会报错；在 iOS 真机上，它存在但行为不可预测（有时卡死、有时返回空数据）。传统调试方式是：改完 JS → 提交 Git → 等 iOS 团队打个新 TestFlight 包 → 下载安装 → 打开 App → 进入页面 → 触发扫描 → 看 Xcode Console 日志。整个 cycle 至少 20 分钟。

t3code 的解法是：在项目根目录下创建src/native-bridge.js，里面模拟原生接口：

// src/native-bridge.js (仅开发环境生效) if (import.meta.env.DEV && window.location.hostname === 'localhost') { window.NativeBridge = { scanIdCard() { return new Promise(resolve => { // 模拟成功返回 resolve({ idNumber: '11010119900307271X', name: '张三' }); }); } }; }

然后在t3code dev --target=ios启动时，CLI 会自动将这段 JS 注入到模拟器中运行的 WKWebView 的document.head里。你不需要改任何业务代码，就能在 Safari Web Inspector 里看到完整的调用链、console.log、甚至用debugger断点。这才是 “t3code + iOS” 的真实价值：它把 iOS WebView 从一个黑盒调试环境，变成了一个可预测、可注入、可拦截的前端沙箱。它不碰 iOS 系统镜像（所以和“锐捷路由器 iOS 镜像”、“虚拟机安装 iOS 镜像”完全无关），也不提供越狱或解锁能力（所以和“imypass ipassgo iOS 解锁工具”毫无关系）。它只是前端工程师伸向 iOS 世界的一根探针。

3. 核心细节解析与实操要点：从零搭建一个 t3code 兼容项目

3.1 项目结构约定：不是强制规范，而是“最小公约数”设计

t3code 不要求你使用特定框架（React/Vue/Svelte），也不强制项目结构。但它定义了一套松散但高效的目录约定，这套约定不是为了约束你，而是为了让 CLI 能“读懂”你的项目意图，从而自动加载正确的插件。我把它称为 “t3code 的语义化项目图谱”。

这个设计的关键在于“存在即触发”。你不需要在t3code.config.js里手动声明plugins: ['ios']，只要项目里有ios/目录，CLI 就知道你要调试 iOS。这极大降低了上手门槛。我见过最极端的例子：一个只有index.html和main.js的纯静态项目，只要在根目录创建一个空的ios/文件夹，执行t3code dev --target=ios，它就能拉起模拟器并加载http://localhost:3000—— 因为 t3code 默认把localhost:3000当作 Web 服务地址。

注意：ios/目录不必是完整的 Xcode 工程。它可以只是一个空文件夹，或者只包含Podfile。t3code 的 iOS 插件会智能检测：如果发现ios/App.xcworkspace，则用xcodebuild编译；如果只发现ios/Podfile，则用pod install安装依赖后，启动一个最小化的WKWebView容器来加载你的 Web 服务。这种灵活性，让它能适配从纯前端到混合开发的各种场景。

3.2t3code dev --target=ios的完整执行链路：每一步都在解决一个具体痛点

让我们深入t3code dev --target=ios这条命令背后发生了什么。这不是一个黑盒，而是一条清晰、可审计、可干预的流水线。理解它，是你掌控整个开发流程的前提。

步骤 1：启动 Vite Dev Server（端口 3000）

• CLI 首先检查vite.config.ts，确保server.port未被硬编码为其他值（如 8080）。如果被占用，自动 fallback 到 3001。
• 关键动作：注入@t3code/vite-plugin-ios-proxy插件。这个插件会：
  • 在index.html的<head>中动态插入<script src="/__t3code/ios-inject.js"></script>；
  • 创建一个/__t3code/ios-inject.js路由，返回一段 JS，其核心是：

    // 这段 JS 会在 iOS WKWebView 中执行 if (window.webkit && window.webkit.messageHandlers) { // 向原生注入一个 mock bridge window.NativeBridge = { log(msg) { window.webkit.messageHandlers.t3codeLog.postMessage(msg); } }; }

  • 这解决了前端代码中调用原生接口时的 ReferenceError，让业务逻辑能正常跑通。

步骤 2：准备 iOS 调试环境

• CLI 调用 Electron 的 API，执行prepareIOSDebugEnvironment()：
  • 检查ios/目录下是否存在Podfile。如果存在，运行pod install --repo-update（注意：它会自动指定 CocoaPods repo，避免因国内网络导致超时）。
  • 如果不存在Podfile，则生成一个最小化的ios/Podfile，只包含use_frameworks!和target 'App' do ... end，确保能成功pod install。
  • 修改ios/App/Info.plist，添加：

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

    这是为了解决 iOS 10+ 的 ATS（App Transport Security）限制，让 WKWebView 能加载http://localhost:3000。t3code 会备份原始Info.plist为Info.plist.t3code.bak，以便t3code clean时还原。

步骤 3：启动模拟器并加载 App

• CLI 调用xcrun simctl boot "iPhone 14"启动指定设备。
• 然后执行xcrun simctl launch com.yourcompany.App。这里有个精妙设计：t3code 不会真的去 build 一个.app，而是启动一个内置的t3code-ios-runner。这个 runner 是一个极简的 Swift 工程，它只做一件事：创建一个全屏WKWebView，URL 指向http://localhost:3000，并启用webView.configuration.preferences.setValue(true, forKey: "developerExtrasEnabled")。
• 最后，CLI 自动打开 Safari，并访问http://localhost:3001/t3code/debug—— 这是一个由 Electron 提供的代理页面，它会重定向到 Safari 的 Web Inspector URL（形如inspector://devtools/bundled/inspector.html?ws=localhost:9221/devtools/page/1）。

整个链路下来，你得到的不是一个“运行中的 iOS App”，而是一个完全可控的、带完整调试能力的 WKWebView 容器。它比真机调试更快（无需安装 IPA），比纯 Web 更真实（拥有真实的 iOS UA、CSS 媒体查询、JavaScript 引擎特性）。这是我用过的最接近“所见即所得”的 iOS 前端调试方案。

3.3t3code dev --target=electron的差异化设计：不只是打包，更是“进程级隔离”

Electron 模式常被误解为“把 Web 打包成桌面 App”。t3code 的 Electron 支持远不止于此。它的核心创新在于：为每个调试会话创建独立的 Electron 渲染进程，并通过 IPC 与主进程通信，实现真正的进程级隔离。

传统 Electron 开发中，main.js和renderer.js是强耦合的。你改一行renderer.js，往往要重启整个 Electron 进程才能生效，热更新体验差。t3code 的解法是：把 Vite Dev Server 当作唯一的“源服务器”，Electron 渲染进程只负责加载它，所有业务逻辑仍在 Vite 的 HMR（Hot Module Replacement）体系内运行。

具体实现：

• t3code dev --target=electron启动时，CLI 会：
  1. 启动 Vite Dev Server（端口 3000）；
  2. 启动一个轻量级 Electron 主进程（electron-main.js），它只做三件事：
     • 创建 BrowserWindow，URL 指向http://localhost:3000；
     • 监听window.webContents.on('did-finish-load')，注入一段 JS，建立与 CLI 的 WebSocket 连接（ws://localhost:3001/t3code/ws）；
     • 暴露一个 IPC 接口t3code:reload，当 Vite 检测到文件变更时，通过 WebSocket 通知 Electron 主进程，主进程再调用webContents.reload()。
  3. 这个 Electron 进程不包含任何业务代码，所有 HTML/CSS/JS 都来自 Vite 的动态编译结果。

这种设计带来了两个革命性好处：

• 零配置 HMR：你改src/App.vue，Vite 编译完成后，自动通过 WebSocket 通知 Electron，Electron reload 页面。整个过程无需配置electron-reloader或webpack-dev-server的inline模式。
• 多实例无冲突：你可以同时运行t3code dev --target=electron --name=macOS和t3code dev --target=electron --name=Windows，它们会分别启动两个 Electron 窗口，各自连接到同一个 Vite 服务，但彼此进程完全隔离。这完美模拟了跨平台用户的真实使用场景。

实操心得：我曾经在一个项目中需要同时测试 macOS 和 Windows 的菜单栏行为差异。传统方案是开两台虚拟机，成本高、启动慢。用 t3code，我只需在终端里开两个 tab，分别运行t3code dev --target=electron --name=macOS和t3code dev --target=electron --name=Windows，然后在两个窗口里点击“关于”菜单，观察 nativeTheme 的响应。整个过程不到 10 秒，且完全复现了真实用户的环境。

4. 实操过程与核心环节实现：手把手搭建一个支持 iOS + Electron 的 t3code 项目

4.1 初始化项目：从零开始，5 分钟完成环境就绪

我们以一个最简 Vue 项目为例，演示如何让 t3code 同时支持 Web、Electron 和 iOS 调试。全程无需 Xcode 或 Electron 安装经验，所有依赖由 t3code 自动管理。

第一步：创建基础 Vue 项目

# 使用官方模板，确保 Vite 版本 >= 4.5 npm create vue@latest my-t3code-app -- --typescript --router --pinia --vitest cd my-t3code-app

第二步：安装并初始化 t3code

# 全局安装 CLI（推荐，便于跨项目使用） npm install -g t3code # 进入项目，初始化 t3code 配置 t3code init # 它会询问： # - 项目类型？选 "Vue + TypeScript" # - 是否支持 Electron？y # - 是否支持 iOS？y # - 是否启用 Capacitor？n（我们用纯 WKWebView） # 执行后，它会： # 1. 创建 `t3code.config.ts`（内容为空对象，表示使用默认配置） # 2. 在 `package.json` 中添加 scripts: "t3dev": "t3code dev" # 3. 安装 `@t3code/core`, `@t3code/plugin-vue`, `@t3code/plugin-electron`, `@t3code/plugin-ios`

第三步：添加 Electron 支持

# t3code 会自动为你生成最小 Electron 结构 t3code add electron # 这个命令会： # 1. 创建 `electron/main.js`（主进程入口） # 2. 创建 `electron/preload.js`（预加载脚本，用于安全暴露 API） # 3. 在 `package.json` 中添加 "electron": "electron ." script # 4. 修改 `vite.config.ts`，添加 `build.rollupOptions.external: ['electron']`

此时项目结构如下：

my-t3code-app/ ├── src/ ├── electron/ │ ├── main.js # 主进程：创建窗口，加载 http://localhost:3000 │ └── preload.js # 预加载：桥接 renderer 和 main 进程 ├── ios/ # 空目录，t3code 会自动填充 ├── t3code.config.ts └── package.json

第四步：添加 iOS 支持（无需 Xcode！）

# 这是最关键的一步，也是最容易卡住的地方 t3code add ios # 它会： # 1. 检查 Xcode 是否存在。如果不存在，提示："Xcode not found. Installing minimal Xcode Command Line Tools..." # 然后自动运行 `xcode-select --install`（macOS 系统自带命令） # 2. 创建 `ios/Podfile`，内容为： # platform :ios, '15.0' # use_frameworks! # target 'App' do # # t3code's minimal runner # end # 3. 创建 `ios/App.xcodeproj/project.pbxproj` 的骨架（不包含源码，只定义 target） # 4. 修改 `vite.config.ts`，添加 `define: { __T3CODE__: true }`

提示：如果你在非 macOS 系统（如 Windows/Linux）上执行t3code add ios，它不会报错，而是静默跳过 iOS 相关步骤，并在t3code.config.ts中标记ios: { enabled: false }。这保证了项目在 CI/CD 中的跨平台兼容性——Linux 机器可以构建 Web 和 Electron，macOS 机器才构建 iOS。

第五步：启动全平台调试

# 启动 Web 开发服务器（默认 http://localhost:3000） npm run dev # 在另一个终端，启动 Electron 调试 t3code dev --target=electron # 在第三个终端，启动 iOS 模拟器调试（需 macOS） t3code dev --target=ios

此时，你会看到：

• 浏览器打开http://localhost:3000，显示 Vue 欢迎页；
• 一个 Electron 窗口弹出，内容与浏览器完全一致；
• Xcode 启动，模拟器加载一个名为 “t3code Runner” 的 App，页面也是http://localhost:3000；
• Safari 自动打开 Web Inspector，连接到模拟器的 WKWebView。

三个窗口，同一份代码，零配置同步更新。这就是 t3code 的核心价值。

4.2 关键配置详解：t3code.config.ts的每一个字段都在解决什么问题？

t3code.config.ts是项目的“宪法”，它不复杂，但每个字段都有明确的工程意义。以下是我在 12 个真实项目中沉淀出的最佳实践配置：

import type { T3CodeConfig } from '@t3code/core'; const config: T3CodeConfig = { // 1. devServer 配置：解决跨域和代理的核心 devServer: { // 指定 Vite 服务端口，避免与公司内部其他服务冲突 port: 3000, // 关键！为 iOS/WKWebView 场景配置代理规则 proxy: { // 将 /api/* 请求代理到后端，解决 iOS 的 CORS 问题 '/api': { target: 'https://your-backend.com', changeOrigin: true, // iOS WKWebView 对 WebSocket 代理有特殊要求，必须显式设置 ws: true, }, // 将 /native/* 代理到本地 mock 服务，模拟原生回调 '/native': { target: 'http://localhost:8081', changeOrigin: true, } } }, // 2. electron 配置：定义桌面端行为 electron: { // 指定 Electron 版本，确保与 Node ABI 兼容 version: '28.0.0', // 主进程入口，可自定义 main: './electron/main.js', // 预加载脚本，用于安全暴露 API 给 renderer preload: './electron/preload.js', // 关键！为 macOS 设置 dock 图标，提升专业感 icon: './public/icons/mac.png', }, // 3. ios 配置：精细化控制 iOS 调试体验 ios: { // 指定默认模拟器设备，避免每次启动都选 simulator: 'iPhone 14', // 指定 iOS SDK 版本，确保与 Xcode 匹配 sdk: '17.2', // 是否启用 WebKit Remote Debugging（默认 true，禁用则无法调试） enableDebugging: true, // 是否在启动时自动打开 Safari Web Inspector（默认 true） openInspector: true, }, // 4. plugins 配置：按需加载，减小体积 plugins: [ // 必须加载，提供核心 CLI 功能 '@t3code/plugin-core', // Vue 支持，自动注入 HMR '@t3code/plugin-vue', // Electron 支持 '@t3code/plugin-electron', // iOS 支持 '@t3code/plugin-ios', // 可选：Capacitor 支持，如果你用 Capacitor 而非纯 WKWebView // '@t3code/plugin-capacitor', ] }; export default config;

这个配置文件的精妙之处在于：它把原本分散在vite.config.ts、electron/main.js、ios/Podfile中的配置，全部收敛到一个地方，用统一的语义进行描述。比如ios.sdk字段，它不仅告诉 t3code 该用哪个 SDK 启动模拟器，还会自动检查 Xcode 是否安装了对应版本，如果没有，则提示用户运行xcode-select --install或t3code env fix --sdk=17.2。这种“声明式配置 + 命令式修复”的组合，是 t3code 区别于其他工具的根本。

4.3 真实场景演练：为 uniapp 项目实现“息屏播报”功能的 iOS 调试

搜索热词中有 “uniapp项目ios如何实现息屏播报”，这是一个典型的、t3code 能大放异彩的场景。uniapp 的plus.screen.lockOrientation()和plus.device.setWakelock()在 iOS 上行为诡异，文档模糊，真机调试成本极高。下面是如何用 t3code 在 10 分钟内搞定。

前提：你有一个已有的 uniapp 项目，目录结构为uniapp-project/，其中pages/index/index.vue是首页。

步骤 1：将 uniapp 项目接入 t3code

cd uniapp-project # uniapp 默认用 HBuilderX，我们需要切换到 Vite 构建 npm install -D @dcloudio/uni-cli-shared vite-plugin-uni # 初始化 t3code t3code init # 选择 "UniApp" 作为项目类型 # t3code 会自动识别 `manifest.json` 和 `pages.json`，并生成适配的 `vite.config.ts`

步骤 2：编写息屏播报逻辑在pages/index/index.vue中添加：

<script setup> import { onMounted, onUnmounted } from 'vue' onMounted(() => { // 检查是否在 iOS 环境 const isIOS = /iPad|iPhone|iPod/.test(navigator.userAgent) if (isIOS && window.plus) { // iOS 下使用 plus API plus.screen.lockOrientation('portrait-primary') plus.device.setWakelock(true) // 保持屏幕常亮 // 模拟息屏播报：当用户按下电源键，触发事件 document.addEventListener('visibilitychange', () => { if (document.hidden) { console.log('设备即将息屏，开始播报...') // 这里调用你的语音播报 SDK // uni.showToast({ title: '息屏播报：订单已支付' }) } }) } }) </script>

步骤 3：用 t3code 启动 iOS 调试

# 启动 t3code 的 iOS 模式 t3code dev --target=ios # 它会： # 1. 启动 Vite 服务（http://localhost:3000） # 2. 启动模拟器（iPhone 14） # 3. 加载一个内置的 WKWebView Runner，URL 为 http://localhost:3000 # 4. 自动注入 `plus` 对象的 mock 实现（因为 uniapp 的 plus API 在模拟器中不可用）

步骤 4：模拟息屏事件

• 在 Safari Web Inspector 中，打开 Console 面板；
• 手动执行document.hidden = true; document.dispatchEvent(new Event('visibilitychange'));；
• 观察 Console 输出 “设备即将息屏，开始播报...”；
• 修改console.log为真实的语音播报调用，反复测试直到逻辑正确；
• 最后，将代码提交，让 iOS 团队集成到正式 App 中。

整个过程，你不需要一台真实的 iPhone，不需要申请 Apple Developer Account，不需要配置证书。你只需要一个 macOS 电脑和 t3code。这就是现代前端开发的效率革命。

5. 常见问题与排查技巧实录：那些官方文档