miaoda-expo-devkit 0.1.1-beta.11 → 0.1.1-beta.110

package/README.md

@@ -7,6 +7,20 @@ Expo / React Native 开发环境工具集，通过 Metro 构建层注入以下
 - **Bundle 首部注入** — 在 expo-router 初始化之前执行自定义脚本
 - **HMR postMessage 控制** — 通过 `window.postMessage` 在运行时启动或停止 Fast Refresh
 - **LogBox 屏蔽** — web 平台禁用 Expo 全屏错误遮罩
+- **Metro transform 缓存持久化** — 将缓存目录固定到项目根目录（可通过 `METRO_CACHE_DIR` 指定），容器/CI 重启后不丢失
+- **构建耗时日志** — 将 bundle 总耗时和每个 cache miss 文件的 transform 耗时写入 JSONL 文件（通过 `METRO_TRANSFORM_LOG` 启用）
+- **esbuild minifier** — 生产构建时将 Metro minifier 切换为 esbuild（比 terser 快数十倍）
+- **WASM 支持** — 将 `.wasm` 加入 assetExts，修复 expo-sqlite web worker 打包失败
+- **lucide-react-native 路径解析** — 配合 babel 插件，消除图标子路径 exports 未声明的 warning
+- **workspace node_modules 修复** — 修复沙箱环境中 node_modules 位于祖先目录时 Metro 模块解析和 bundle 请求失败的问题
+- **expo-notifications stub** — Expo Go（Android）中提供 no-op 实现，核心 API 调用时弹出带参数校验的调试 Alert，Dev Build 透传真实模块
+- **expo-media-library stub** — Expo Go / Web 中提供 no-op 实现，`saveToLibraryAsync`、`createAssetAsync`、权限请求等 API 调用时弹出 Alert 提示，Dev Build 原生环境透传真实模块
+- **expo-calendar stub** — Expo Go / Web 中提供 no-op 实现，`getEventsAsync`、`createEventAsync`、`getCalendarsAsync`、权限请求等核心 API 调用时弹出 Alert 提示并校验参数，Dev Build 原生环境透传真实模块
+- **expo-file-system stub** — Web 中将 `expo-file-system` 和 `expo-file-system/legacy` 替换为 no-op stub，核心 API 弹 Dialog 提示，Expo Go / Dev Build 透传真实模块
+- **expo-haptics stub** — Web 中提供 no-op 实现，触觉 API 调用时弹 Dialog 提示参数信息，native 不受影响
+- **expo-contacts stub** — Web / Expo Go 中提供 no-op 实现，联系人 API 调用时弹 Dialog 提示，Dev Build 透传真实模块
+- **expo-image-picker stub** — 桌面 Web 中 `launchCameraAsync` 通过 `getUserMedia` 打开摄像头预览弹窗（浏览器原生 `capture` 属性在 PC 端被忽略），移动端浏览器透传 expo 原实现，Native 不受影响
+- **devkit-lint** — 集成 Oxlint（18 条自定义规则）、Biome、TypeScript 类型检查、以及 `app.json` 字段合法性校验，一条命令完成项目全量静态检查
 
 ## 安装
 
@@ -32,16 +46,16 @@ pnpm install
 ```js
 // metro.config.js
 const { getDefaultConfig } = require('expo/metro-config');
-const { withDevStubs, withEntryInjection } = require('miaoda-expo-devkit/metro');
+const { withDevkit } = require('miaoda-expo-devkit/metro');
 
-const config = getDefaultConfig(__dirname);
-module.exports = withEntryInjection(withDevStubs(config));
+module.exports = withDevkit(getDefaultConfig(__dirname));
 ```
 
-支持与其他 Metro wrapper 链式组合：
+`withDevkit` 已内置所有 wrapper（含 expo-notifications、expo-media-library、expo-calendar stub），无需手动叠加。也可单独使用各 wrapper：
 
 ```js
-module.exports = withNativeWind(withEntryInjection(withDevStubs(config)), { input: './global.css' });
+const { withDevStubs, withEntryInjection, withExpoMediaLibraryStub, withExpoCalendarStub } = require('miaoda-expo-devkit/metro');
+module.exports = withExpoCalendarStub(withExpoMediaLibraryStub(withEntryInjection(withDevStubs(config))));
 ```
 
 ### Sentry 初始化
@@ -220,18 +234,114 @@ expect(onError).toHaveBeenCalledWith(
 | 变量 | 默认值 | 说明 |
 |---|---|---|
 | `SENTRY_OVERRIDE_DSN` | `https://stubPublicKey@o0.ingest.sentry.io/0` | 覆盖 Sentry DSN，可指向本地 relay 等自定义端点 |
+| `METRO_CACHE_DIR` | `projectRoot/.metro-cache` | Metro transform 缓存目录绝对路径，优先级最高，适合容器/CI 挂载外部持久目录 |
+| `METRO_TRANSFORM_LOG` | _(未设置时不记录)_ | 构建日志输出文件的绝对路径（JSONL 格式），仅开发模式（`__DEV__`）下生效 |
+| `EXPO_AI_ERROR_COLLECTOR` | _(未设置时关闭)_ | 设为 `1` 后由 DevKit 管理的 Expo CLI patch 采集当前 Metro 编译状态 |
+| `EXPO_AI_ERROR_FILE` | `<projectRoot>/node_modules/.miaoda-expo/ai-error.json` | AI 当前错误状态文件；支持绝对路径或相对项目根目录的路径 |
+
+### Metro 编译错误采集
+
+DevKit 会通过 pnpm patch 接入 Expo CLI 自己的 Metro reporter wrapper，不修改
+LogBox 或 Metro 核心。启用后，首次 bundle 失败也能在前端启动前写入状态文件：
+
+```sh
+EXPO_AI_ERROR_COLLECTOR=1 npx expo start
+```
+
+默认状态文件位于 `node_modules/.miaoda-expo/ai-error.json`，目录会自动创建。依赖重装
+可能清理这个目录；需要持久化时请设置 `EXPO_AI_ERROR_FILE` 指向项目外部路径。
+
+状态文件只表示“当前编译”：`bundle_build_started` 会立即清除上一次错误，
+`bundling_error` 写入结构化错误，下一次编译成功或失败都会替换旧状态。AI
+进程直接读取这个文件即可，不需要额外的 HTTP 服务或 WebSocket 客户端。
+
+返回对象包含 `status`（`compiling`、`failed`、`succeeded`）和 `error`。失败时
+`error` 至少包含 `type`、`message`、`filename`、`lineNumber`、`column`、
+`errors` 和 `stack`（存在时）。
+
+当前模板为 Expo CLI `55.0.16` 至 `55.0.22` 提供一个范围补丁（`>=55.0.16 <55.0.23`）。
+该范围以外的 CLI 版本不会静默套用补丁；升级时需要先检查发布产物，确认兼容后再调整
+`pnpmfile.cjs` 中的范围和对应测试。
 
 ## 工作原理
 
 ```
 metro.config.js
-  └─ withEntryInjection(withDevStubs(config))
+  └─ withDevkit(config)
+       │
+       ├─ withTransformLogger → unstable_perfLoggerFactory + metro-core Logger
+       │    ├─ CACHE_CONFIG 条目（启动时由 withPersistentCache 写入，含 cache_root / store_class / source）
+       │    ├─ BUNDLING_REQUEST 条目（每次 bundle 请求写一条）
+       │    │    ├─ duration_ms、status、initial_build、graph_node_count
+       │    │    └─ transform_miss_count（cache miss 文件数；0 = 完全命中）
+       │    └─ TRANSFORM_FILE 条目（每个 cache miss 文件写一条，命中则不写）
+       │         └─ file、duration_ms
+       │    （需设置 METRO_TRANSFORM_LOG 且 __DEV__ 才生效）
+       │
+       ├─ withPersistentCache → config.cacheStores
+       │    ├─ 缓存路径优先级：METRO_CACHE_DIR > options.cacheDir > projectRoot/.metro-cache
+       │    └─ 保留 @expo/metro-config FileStore 子类行为（NativeWind skipCache 标志）
+       │
+       ├─ withWorkspaceNodeModules → watchFolders + resolver.nodeModulesPaths
+       │    ├─ 向上查找祖先目录的 node_modules，加入 watchFolders
+       │    └─ 若 .pnpm 是指向外部路径的 symlink，也将外部真实路径加入 watchFolders
+       │
+       ├─ withWasmSupport → resolver.assetExts
+       │    └─ 将 .wasm 加入 assetExts，修复 expo-sqlite web worker 打包
+       │
+       ├─ withCssInterop → 为 expo-image / expo-camera 等注入 NativeWind cssInterop
+       │
+       ├─ withEsbuildMinify → transformer.minifierPath（仅生产构建）
+       │    └─ 切换为 metro-minify-esbuild，清空 terser 专属 minifierConfig
+       │
+       ├─ withLucideResolver → resolver.resolveRequest
+       │    └─ lucide-react-native/dist/** 子路径 → 绝对文件路径（绕过 exports 检查）
+       │         └─ 自动检测 .mjs（>= 1.9）vs .js（1.8.x）扩展名
        │
        ├─ withDevStubs → resolver.resolveRequest
        │    ├─ @sentry/react-native        →  dist/stubs/sentry-react-native-stub.js  （全平台）
        │    └─ @expo/log-box               →  dist/stubs/no-op-logbox.js              （仅 web）
        │
-       └─ withEntryInjection → resolver.resolveRequest
+       ├─ withExpoNotificationsStub → resolver.resolveRequest
+       │    └─ expo-notifications          →  dist/stubs/expo-notifications-stub.js   （仅 Android）
+       │         ├─ Expo Go：no-op + 调试 Alert（含参数校验）
+       │         └─ Dev Build：透传真实 expo-notifications
+       │
+       ├─ withExpoMediaLibraryStub → resolver.resolveRequest
+       │    └─ expo-media-library          →  dist/stubs/expo-media-library-stub.js   （全平台）
+       │         ├─ Expo Go / Web：no-op + Alert 提示（不崩溃）
+       │         └─ Dev Build（原生）：透传真实 expo-media-library
+       │
+       ├─ withExpoCalendarStub → resolver.resolveRequest
+       │    └─ expo-calendar               →  dist/stubs/expo-calendar-stub.js        （全平台）
+       │         ├─ Expo Go / Web：no-op + Alert 提示 + 参数校验（不崩溃）
+       │         └─ Dev Build（原生）：透传真实 expo-calendar
+       │
+       ├─ withExpoFileSystemStub → resolver.resolveRequest
+       │    ├─ expo-file-system/legacy      →  dist/stubs/expo-file-system-stub.js    （全平台）
+       │    └─ expo-file-system             →  dist/stubs/expo-file-system-next-stub.js
+       │         ├─ Web：no-op + Dialog 提示（不崩溃）
+       │         └─ Expo Go / Dev Build（原生）：透传真实模块
+       │
+       ├─ withExpoHapticsStub → resolver.resolveRequest
+       │    └─ expo-haptics                →  dist/stubs/expo-haptics-stub.js         （仅 web）
+       │         ├─ Web：no-op + Dialog 提示（不崩溃）
+       │         └─ native：透传真实 expo-haptics
+       │
+       ├─ withExpoContactsStub → resolver.resolveRequest
+       │    └─ expo-contacts               →  dist/stubs/expo-contacts-stub.js        （仅 web）
+       │         ├─ Web / Expo Go：no-op + Dialog 提示（不崩溃）
+       │         └─ Dev Build（原生）：透传真实 expo-contacts
+       │
+       ├─ withExpoImagePickerStub → resolver.resolveRequest
+       │    └─ expo-image-picker           →  dist/stubs/expo-image-picker-stub.js    （仅 web）
+       │         ├─ 桌面 Web：launchCameraAsync → getUserMedia + #__devkit_camera_overlay__ 弹窗
+       │         │    ├─ 点"拍照"：canvas.toDataURL → ImagePickerResult { canceled:false, assets }
+       │         │    └─ 点"取消"：返回 { canceled:true, assets:null }
+       │         ├─ 移动端浏览器：透传 expo 原实现（capture 属性正常工作）
+       │         └─ getUserMedia 不可用：降级透传 expo 原实现（不崩溃）
+       │
+       └─ withEntryInjection → resolver.resolveRequest（仅 __DEV__）
             └─ expo-router/entry-classic   →  dist/stubs/expo-router-entry-stub.js
                  ├─ require('./entry-inject')           ← 注入脚本（bundle 首部执行）
                  │    ├─ globalThis.__DEVKIT_INJECTED__ = true
@@ -262,10 +372,90 @@ sentry-react-native-stub.js
 | 子路径 | 文件 | 内容 |
 |---|---|---|
 | `.` | `dist/index.js` | `SentryCapture`、`MetroSymbolicator`、全部类型 |
-| `./metro` | `dist/metro.js` | `withDevStubs`、`withEntryInjection` |
+| `./metro` | `dist/metro.js` | `withDevkit`、`withDevStubs`、`withEntryInjection`、`withPersistentCache`、`withTransformLogger`、`withExpoNotificationsStub`、`withExpoMediaLibraryStub`、`withExpoCalendarStub` 等全部 Metro wrapper |
 | `./babel-plugin-jsx-source` | `dist/babel/plugin-jsx-source.js` | Babel 插件：为 JSX 注入 source 信息 |
+| `./babel-preset` | `dist/babel/preset.js` | Babel Preset：集成 jsx-source 和 lucide 插件 |
 | `./sentry-react-native-stub` | `dist/stubs/sentry-react-native-stub.js` | `@sentry/react-native` 模块替换 stub |
 | `./no-op-logbox` | `dist/stubs/no-op-logbox.js` | LogBox no-op stub |
+| `./expo-notifications-stub` | `dist/stubs/expo-notifications-stub.js` | `expo-notifications` Expo Go Android stub |
+| `./expo-media-library-stub` | `dist/stubs/expo-media-library-stub.js` | `expo-media-library` Expo Go / Web stub |
+| `./expo-calendar-stub` | `dist/stubs/expo-calendar-stub.js` | `expo-calendar` Expo Go / Web stub |
+| `./expo-file-system-stub` | `dist/stubs/expo-file-system-stub.js` | `expo-file-system/legacy` Web stub |
+| `./expo-file-system-next-stub` | `dist/stubs/expo-file-system-next-stub.js` | `expo-file-system` 新版 API Web stub |
+| `./expo-haptics-stub` | `dist/stubs/expo-haptics-stub.js` | `expo-haptics` Web stub |
+| `./expo-contacts-stub` | `dist/stubs/expo-contacts-stub.js` | `expo-contacts` Web / Expo Go stub |
+| `./expo-image-picker-stub` | `dist/stubs/expo-image-picker-stub.js` | `expo-image-picker` 桌面 Web stub |
+
+---
+
+## devkit-lint
+
+`devkit-lint` 是内置的静态检查命令，一次执行涵盖四个阶段：
+
+```
+oxlint   →  biome   →  tsc --noEmit   →  app.json schema 校验
+```
+
+所有阶段都会跑完再退出，最终汇总哪个阶段失败。
+
+### 使用
+
+```json
+// package.json
+{
+  "scripts": {
+    "lint": "devkit-lint"
+  }
+}
+```
+
+```sh
+bun run lint
+```
+
+### app.json 字段校验
+
+`devkit-lint` 在最后一步用 [`@expo/schemer`](https://github.com/expo/expo/tree/main/packages/@expo/schemer) 对 `app.json` 做 JSON Schema 校验，拦截字段值错误（枚举值不合法、类型错误等）。
+
+典型场景：`"orientation": "all"` 不是合法的 Expo 枚举值（合法值为 `"default" | "portrait" | "landscape"`），这类错误原本只会在 Gradle/AAPT 阶段（构建约 1 分钟后）以晦涩的资源链接报错暴露，现在在 lint 阶段秒级报出：
+
+```
+[app.json schema errors]
+  /path/to/project/app.json: field 'orientation' — must be equal to one of the allowed values (got: "all")
+
+────────────────────────────────────────────────────────────
+RESULT: FAILED — Found errors in: app.json
+```
+
+#### Schema 来源与存储
+
+Expo 随每个 SDK 版本在其文档站发布版本化 JSON Schema（位于 `docs/public/static/schemas/v{VERSION}/app-config-schema.json`）。devkit 将对应版本的 schema 文件复制到 `src/schemas/app-config-schema-v55.json`，随 CLI bundle（`dist/cli/lint.js`）一起内联打包。
+
+这意味着：
+
+- **完全离线**：不在运行时请求 `exp.host` 或任何外部服务，在无网络的 CI 容器中也能正常工作
+- **版本固定**：schema 与 Expo SDK 55 对应，校验结果与 Expo 官方行为一致
+- **零运行时依赖**：`@expo/schemer`（及其依赖 `ajv`）在构建时内联进 `dist/cli/lint.js`，消费方无需安装额外依赖
+
+#### 升级 Expo SDK 时的 schema 更新
+
+当项目升级 Expo SDK 版本时，需同步更新 schema 文件：
+
+```sh
+# 从 Expo 源码仓库复制新版 schema（以升级到 v56 为例）
+cp /path/to/expo/docs/public/static/schemas/v56.0.0/app-config-schema.json \
+   packages/devkit/src/schemas/app-config-schema-v56.json
+
+# 删除旧版 schema 文件
+rm packages/devkit/src/schemas/app-config-schema-v55.json
+```
+
+并相应修改 `src/cli/lint.ts` 中的 import 路径：
+
+```ts
+// 改为
+import rawSchema from '../schemas/app-config-schema-v56.json';
+```
 
 ---
 
@@ -388,6 +578,183 @@ LogBox no-op stub，用于 web 平台禁用 Expo 全屏错误遮罩。
 
 ---
 
+### expo-notifications-stub.js
+
+`expo-notifications` 模块替换 stub，由 `withExpoNotificationsStub()` 在 Metro 层注入（**仅 Android 平台**）。
+
+**背景：** Expo SDK 53 起，`expo-notifications` 的 Android native module 已从 Expo Go 中移除，直接 import 会在 Expo Go 启动时崩溃。
+
+**运行时行为：**
+- **Expo Go（Android）**：提供 no-op 实现，`requestPermissionsAsync`、`setNotificationChannelAsync`、`scheduleNotificationAsync` 等核心 API 调用时弹出带参数校验的调试 Alert
+- **Development Build（Android）**：透传真实 `expo-notifications`，功能完全正常
+- **iOS（任意）**：不经过此 stub，直接使用真实 `expo-notifications`
+
+**手动验证：** 在 `devkit-e2e` App 中扫码进入「Notification Stub 验证」页面，逐按钮触发并对照期望结果。
+
+---
+
+### expo-media-library-stub.js
+
+`expo-media-library` 模块替换 stub，由 `withExpoMediaLibraryStub()` 在 Metro 层注入（**全平台**）。
+
+**背景：** `expo-media-library` 依赖原生相册 API，在 Expo Go 和 Web 环境中不可用，调用 `saveToLibraryAsync` 等 API 会直接崩溃。
+
+**运行时行为：**
+- **Expo Go / Web**：提供 no-op 实现，以下 API 调用时弹出 Alert 提示（不崩溃）：
+  - `usePermissions()` — 返回 `{ status: 'undetermined', granted: false }`，`requestPermission()` 弹 Alert
+  - `requestPermissionsAsync()` / `getPermissionsAsync()` — 前者弹 Alert，后者静默返回 denied
+  - `saveToLibraryAsync(uri)` — 弹 Alert 显示操作和 URI（超 60 字符自动截断）
+  - `createAssetAsync(uri)` — 弹 Alert 并返回合法的伪资产对象
+  - 其他未知 API — Proxy 兜底，静默返回 `undefined`；以 `PermissionsAsync` 结尾的 API 返回 denied 结构
+- **Development Build（原生）**：透传真实 `expo-media-library`，功能完全正常
+
+**Alert 消息格式：**
+```
+保存到相册
+Expo Go 扫码预览不支持访问手机相册
+操作: 图片: file:///tmp/test.jpg
+发布为正式 App 后可正常使用
+```
+
+**手动验证：** 在 `devkit-e2e` App 中扫码进入「Media Library Stub 验证」页面，逐按钮触发并对照期望结果。
+
+---
+
+### expo-calendar-stub.js
+
+`expo-calendar` 模块替换 stub，由 `withExpoCalendarStub()` 在 Metro 层注入（**全平台**）。
+
+**背景：** `expo-calendar` 依赖原生系统日历 API，在 Expo Go 和 Web 环境中不可用，调用 `getEventsAsync` 等 API 会直接崩溃。
+
+**运行时行为：**
+- **Expo Go / Web**：提供 no-op 实现，以下 API 调用时弹出 Alert / Dialog 提示（不崩溃）：
+  - `useCalendarPermissions()` / `useRemindersPermissions()` — 初始返回 `undetermined`，`requestPermission()` 弹 Alert
+  - `requestCalendarPermissionsAsync()` / `requestRemindersPermissionsAsync()` — 弹 Alert 提示，返回 denied
+  - `getCalendarPermissionsAsync()` / `getRemindersPermissionsAsync()` — 静默返回 denied
+  - `getCalendarsAsync(entityType?)` — 弹 Alert 显示查询类型，返回空数组
+  - `createCalendarAsync(details)` — 弹 Alert 含名称和颜色，校验 `details.title` 非空
+  - `updateCalendarAsync(id, details)` / `deleteCalendarAsync(id)` — 弹 Alert 含日历 ID，校验 ID 格式
+  - `getEventsAsync(calendarIds, startDate, endDate)` — 弹 Alert 含时间范围，校验 calendarIds 非空及日期合法性，返回空数组
+  - `createEventAsync(calendarId, eventData)` — 弹 Alert 含标题和时间，Android 下校验 startDate/endDate
+  - `updateEventAsync(id, details)` / `deleteEventAsync(id)` — 弹 Alert 含事件 ID，校验 ID 格式
+  - 其他未知 API — Proxy 兜底，静默返回 `undefined`；以 `PermissionsAsync` 结尾的 API 返回 denied 结构
+- **Development Build（原生）**：透传真实 `expo-calendar`，功能完全正常
+
+**枚举常量**（stub & Dev Build 均可用）：
+`EntityTypes`、`Frequency`、`Availability`、`CalendarType`、`EventStatus`、`SourceType`、
+`AttendeeRole`、`AttendeeStatus`、`AttendeeType`、`AlarmMethod`、`EventAccessLevel`、
+`CalendarAccessLevel`、`ReminderStatus`、`DayOfTheWeek`、`MonthOfTheYear`
+
+**Alert 消息格式（合规示例）：**
+```
+创建日历事件
+秒哒扫码预览不支持访问手机日历
+
+日历 ID: cal1
+标题: 团队会议
+开始: 2025/1/1 10:00:00
+结束: 2025/1/1 11:00:00
+
+✅ 参数合规
+发布为正式 App 后可正常使用
+```
+
+**手动验证：** 在 `devkit-e2e` App 中扫码进入「Calendar Stub 验证」页面，逐按钮触发并对照期望结果。
+
+---
+
+### expo-file-system-stub.js / expo-file-system-next-stub.js
+
+`expo-file-system` 模块替换 stub，由 `withExpoFileSystemStub()` 在 Metro 层注入（**全平台**）。
+
+**背景：** `expo-file-system` 的文件 API 在 Web 端不可用：legacy API 底层方法缺失会抛 `UnavailabilityError`；新版 API（`File` / `Directory`）基类缺少 `validatePath()`，`new File(...)` 会抛 `TypeError: this.validatePath is not a function`。
+
+**拦截路径：**
+- `expo-file-system/legacy` → `expo-file-system-stub.js`（legacy API）
+- `expo-file-system` → `expo-file-system-next-stub.js`（新版 File/Directory/Paths API）
+
+**运行时行为：**
+- **Web**：提供 no-op 实现，核心 API 调用时弹出 Dialog 提示（不崩溃）
+- **Expo Go / Development Build（原生）**：透传真实 `expo-file-system`，功能完全正常
+
+---
+
+### expo-haptics-stub.js
+
+`expo-haptics` 模块替换 stub，由 `withExpoHapticsStub()` 在 Metro 层注入（**仅 web 平台**）。
+
+**背景：** Web 没有振动/触觉硬件 API，`expo-haptics` 在 web 会运行时崩溃。
+
+**运行时行为：**
+- **Web**：提供 no-op 实现，`impactAsync`、`notificationAsync`、`selectionAsync` 调用时弹出 Dialog 提示参数信息（不崩溃）；枚举常量（`ImpactFeedbackStyle`、`NotificationFeedbackType` 等）正常可用
+- **Expo Go / Development Build（native）**：透传真实 `expo-haptics`，功能完全正常
+
+---
+
+### expo-contacts-stub.js
+
+`expo-contacts` 模块替换 stub，由 `withExpoContactsStub()` 在 Metro 层注入（**仅 web 平台**）。
+
+**背景：** `expo-contacts` 依赖 native module，在 Web 和 Expo Go 中不可用。
+
+**运行时行为：**
+- **Web / Expo Go**：提供 no-op 实现，联系人 API 调用时弹出 Dialog 提示（不崩溃）
+- **Development Build（原生）**：透传真实 `expo-contacts`，功能完全正常
+
+---
+
+### expo-image-picker-stub.js
+
+`expo-image-picker` 模块替换 stub，由 `withExpoImagePickerStub()` 在 Metro 层注入（**仅 web 平台**）。
+
+**背景：** `expo-image-picker` 的 `launchCameraAsync` 在 web 上底层使用 `<input type="file" capture="environment">`。桌面浏览器（Chrome、Firefox、Safari）**有意忽略 `capture` 属性**，直接弹出文件选择框而不是摄像头。这是浏览器厂商的硬限制，无法通过任何 HTML 属性或 meta 标签绕过。
+
+**运行时行为：**
+- **桌面 Web（非 mobile UA）**：`launchCameraAsync` 调用 `navigator.mediaDevices.getUserMedia` 打开摄像头预览弹窗（`#__devkit_camera_overlay__`），用户点击"📷 拍照"后截取一帧并以 `data:image/jpeg` 格式返回，点击"取消"返回 `{ canceled: true }`
+- **移动端浏览器（Android Chrome / iOS Safari）**：透传 expo 原实现，`capture` 属性在移动端正常调起系统相机
+- **`getUserMedia` 不可用**（无摄像头或浏览器限制）：静默降级，透传 expo 原实现（不崩溃）
+- **Native（iOS / Android）**：Metro resolver 不拦截，直接使用原生 `expo-image-picker`，功能完全不变
+
+**弹窗 DOM 结构（供 Playwright 定位）：**
+```html
+<div id="__devkit_camera_overlay__">   <!-- 全屏遮罩 -->
+  <div>                                <!-- 面板 -->
+    <p>拍照</p>
+    <video autoplay muted playsinline> <!-- 摄像头预览 -->
+    <div>
+      <button>📷 拍照</button>
+      <button>取消</button>
+    </div>
+    <p><!-- 错误信息（getUserMedia 失败时显示） --></p>
+  </div>
+</div>
+```
+
+**返回值格式（与 expo 原实现兼容）：**
+```ts
+// 拍照成功
+{
+  canceled: false,
+  assets: [{
+    uri: 'data:image/jpeg;base64,...',
+    width: 640,
+    height: 480,
+    type: 'image',
+    fileName: 'photo_1234567890.jpg',
+    mimeType: 'image/jpeg',
+    base64: null,
+    exif: null,
+  }]
+}
+
+// 取消
+{ canceled: true, assets: null }
+```
+
+**E2E 测试：** `devkit-e2e/tests/e2e/image-picker-stub.spec.ts`，使用 `addInitScript` mock `getUserMedia`（注入 canvas stream 替代真实摄像头），覆盖弹窗出现/消失、拍照返回结果、取消、降级等场景。
+
+---
+
 ## Babel 插件：jsx-source
 
 `babel-plugin-jsx-source` 为 JSX 元素注入 source 属性（文件路径、行列号），用于开发调试。通过 `dataSet` 对象注入，这是 React Web 可识别的数据通道。
@@ -434,3 +801,120 @@ module.exports = {
 |---|---|---|---|
 | `rootDir` | `string` | - | 项目根目录，用于计算相对路径。不提供则使用绝对路径 |
 | `excludePaths` | `string[]` | `[]` | 跳过注入的路径模式列表（相对于 rootDir 的路径片段） |
+
+---
+
+## Babel 插件：lucide-react-native
+
+Metro 没有 tree-shaking，直接写 `import { Star } from "lucide-react-native"` 会把整个图标库（约 1500 个图标）打进 bundle。`babel-plugin-lucide-react-native` 在编译阶段将具名导入改写为直接按文件导入，彻底规避这个问题。
+
+**转换效果：**
+
+```ts
+// 转换前
+import { Star, BookOpen } from "lucide-react-native";
+
+// 转换后（CJS，默认）
+import _Star     from "lucide-react-native/dist/cjs/icons/star";
+import _BookOpen from "lucide-react-native/dist/cjs/icons/book-open";
+```
+
+### 配置
+
+推荐通过内置 Preset 一次性启用所有 Babel 插件：
+
+```js
+// babel.config.js
+module.exports = {
+  presets: [['miaoda-expo-devkit/babel-preset', { excludePaths: ['src/components/ui'] }]],
+};
+```
+
+也可以单独使用：
+
+```js
+module.exports = {
+  plugins: [['miaoda-expo-devkit/babel-plugin-lucide-react-native']],
+};
+```
+
+### 选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `useES` | `boolean` | `false` | 使用 ESM 格式（`dist/esm/icons/`）而非默认的 CJS |
+
+### 支持的写法
+
+插件可识别所有常见的图标引用写法：
+
+```ts
+import { BookOpen, Star, Crown } from "lucide-react-native";
+
+// JSX 直接使用
+<BookOpen size={24} />
+
+// 赋值给变量
+const icon = BookOpen;
+
+// 对象 value
+const ITEMS = [{ icon: BookOpen }, { icon: Star }];
+
+// 计算属性 key
+const map = { [BookOpen]: 'read' };
+
+// 数组、三元、函数参数
+const list = [BookOpen, Star];
+const active = flag ? BookOpen : Star;
+renderIcon(Crown);
+
+// 导入别名
+import { BookOpen as ReadIcon } from "lucide-react-native";
+<ReadIcon />
+
+// re-export
+export { Star, BookOpen as ReadIcon } from "lucide-react-native";
+```
+
+### 版本兼容性
+
+插件在运行时探测 `lucide-react-native` 的实际目录结构，自动适配新旧版本的路径差异（`>= 1.9` 新增 `icons/` 子目录；旧版 `1.8.x` 图标直接位于 `dist/cjs/`），lucide 升级时无需修改配置。
+
+---
+
+## pnpm 配置依赖与兼容补丁
+
+DevKit 可以作为 pnpm `configDependency`，在普通依赖解析前集中注入经过验证的 Expo/React Native 兼容补丁。要求 pnpm `>=10.32.0`。
+
+发布新版 DevKit 后，在应用工作区根目录执行：
+
+```bash
+pnpm add --config --registry=https://registry.npmjs.org/ miaoda-expo-devkit@<version>
+```
+
+由于现有包名不属于 pnpm 的自动插件命名空间，还需要在 `pnpm-workspace.yaml` 中指定 hook：
+
+```yaml
+pnpmfile:
+  - node_modules/.pnpm-config/miaoda-expo-devkit/pnpmfile.cjs
+```
+
+本仓库的 `scripts/build.sh` 会自动把生成 Template 的 `pnpmfile` 改为上述 config dependency 路径，并写入精确版本和完整性校验；无需在生成产物中维护额外的 `.pnpmfile.cjs`。
+
+DevKit 当前管理以下补丁：
+
+- `@shopify/react-native-skia@2.4.18`
+- `expo@55.0.6`（固定 `expo-audio@55.0.6` 和 `expo-video@55.0.5` 的 Expo 兼容版本表）
+- `expo-modules-core@55.0.15`
+- `react-native-css-interop@0.2.6`
+- `react-native-reanimated@4.2.1`
+
+迁移历史项目时，hook 会计算同名本地 patch 的 SHA-256：已知模板 patch 会自动切换到 DevKit 内置文件；内容不同的项目定制 patch 会继续优先，并输出警告。项目中其他 `patchedDependencies` 不受影响。迁移后必须重新生成并提交 `pnpm-lock.yaml`。
+
+发布前可用一条命令运行轻量集成测试：
+
+```bash
+pnpm --dir packages/devkit test:patches
+```
+
+该命令会自动构建并打包 DevKit，在临时项目中模拟 pnpm 安装 Config Dependency 后的目录布局，安装五个精确版本的目标依赖，检查补丁后的文件及 lockfile，然后执行 frozen-lockfile 复装并清理临时目录。它不会运行 Expo Prebuild、Gradle 或 Android 编译。

package/biome-config.json

@@ -1,14 +1,52 @@
 {
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"includes": [
+			"src/**/*.{js,jsx,ts,tsx,css,scss}",
+			"tailwind.config.js"
+		],
+		"experimentalScannerIgnores": [
+			"src/components/ui/**"
+		]
+	},
 	"linter": {
 		"enabled": true,
 		"rules": {
 			"recommended": false,
 			"correctness": {
 				"noUndeclaredDependencies": "error"
+			},
+			"style": {
+				"noRestrictedImports": {
+					"level": "error",
+					"options": {
+						"paths": {
+							"expo-barcode-scanner": "Deprecated in SDK 51+. Use expo-camera with barcode scanning instead.",
+							"expo-background-fetch": "Deprecated. Use expo-background-task instead.",
+							"expo-av": "Removed in SDK 55. Use expo-video for video and expo-audio for audio instead."
+						}
+					}
+				}
 			}
 		}
 	},
 	"formatter": {
 		"enabled": false
-	}
+	},
+	"overrides": [
+		{
+			"includes": ["tailwind.config.js"],
+			"linter": {
+				"rules": {
+					"style": {
+						"noCommonJs": "off"
+					}
+				}
+			}
+		}
+	]
 }

package/dist/babel/plugin-jsx-source.d.ts

@@ -1,4 +1,4 @@
-import { types, PluginObj } from '@babel/core';
+import { types, PluginObj, PluginPass } from '@babel/core';
 
 /**
  * babel-plugin-jsx-source
@@ -37,12 +37,19 @@ interface JsxSourcePluginOptions {
     rootDir?: string;
     /** 需要跳过注入的路径模式列表（相对于 rootDir 的路径片段） */
     excludePaths?: string[];
+    /** 需要跳过注入的包名列表，从这些包导入的组件不会被注入 */
+    excludePackages?: string[];
+}
+interface PluginState extends PluginPass {
+    opts: JsxSourcePluginOptions;
+    /** 当前文件中来自被排除包的本地标识符集合，Program 阶段初始化 */
+    excludedComponents: Set<string>;
 }
 /**
  * Babel 插件：为 JSX 元素注入 dataSet
  */
 declare function babelPluginJsxSource({ types: t, }: {
     types: typeof types;
-}): PluginObj;
+}): PluginObj<PluginState>;
 
 export { type JsxSourcePluginOptions, babelPluginJsxSource as default };

package/dist/babel/plugin-jsx-source.js

@@ -23,6 +23,7 @@ __export(plugin_jsx_source_exports, {
   default: () => babelPluginJsxSource
 });
 module.exports = __toCommonJS(plugin_jsx_source_exports);
+var DEFAULT_EXCLUDE_PACKAGES = ["react-native-gifted-charts"];
 var DATASET_PROP_NAME = "dataSet";
 var MD_ID_KEY = "mdId";
 var MD_CONTENT_KEY = "componentContent";
@@ -106,12 +107,32 @@ function babelPluginJsxSource({
   return {
     name: "babel-plugin-jsx-source",
     visitor: {
+      Program(_path, state) {
+        const excludePackages = [
+          ...DEFAULT_EXCLUDE_PACKAGES,
+          ...state.opts.excludePackages ?? []
+        ];
+        const excluded = /* @__PURE__ */ new Set();
+        for (const node of _path.node.body) {
+          if (t.isImportDeclaration(node) && excludePackages.some(
+            (pkg) => node.source.value === pkg || node.source.value.startsWith(pkg + "/")
+          )) {
+            for (const specifier of node.specifiers) {
+              excluded.add(specifier.local.name);
+            }
+          }
+        }
+        state.excludedComponents = excluded;
+      },
       JSXOpeningElement(path, state) {
         const { opts, filename } = state;
         if (!filename) return;
         if (filename.includes("node_modules")) return;
         if (opts.excludePaths?.some((p) => filename.includes(p))) return;
         if (shouldSkipElement(t, path.node.name)) return;
+        const elementName = path.node.name;
+        if (t.isJSXIdentifier(elementName) && state.excludedComponents.has(elementName.name)) return;
+        if (t.isJSXMemberExpression(elementName) && t.isJSXIdentifier(elementName.object) && state.excludedComponents.has(elementName.object.name)) return;
         const loc = path.node.loc;
         if (!loc) return;
         let filePath = filename;