miaoda-expo-devkit 0.1.1-beta.69 → 0.1.1-beta.70

package/README.md

@@ -7,9 +7,18 @@ 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 不受影响
 
 ## 安装
@@ -224,12 +233,43 @@ 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__`）下生效 |
 
 ## 工作原理
 
 ```
 metro.config.js
   └─ 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  （全平台）
@@ -246,19 +286,35 @@ metro.config.js
        │         └─ Dev Build（原生）：透传真实 expo-media-library
        │
        ├─ withExpoCalendarStub → resolver.resolveRequest
-       │    └─ expo-calendar              →  dist/stubs/expo-calendar-stub.js          （全平台）
+       │    └─ 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）
+       │    └─ 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
+       └─ withEntryInjection → resolver.resolveRequest（仅 __DEV__）
             └─ expo-router/entry-classic   →  dist/stubs/expo-router-entry-stub.js
                  ├─ require('./entry-inject')           ← 注入脚本（bundle 首部执行）
                  │    ├─ globalThis.__DEVKIT_INJECTED__ = true
@@ -289,7 +345,7 @@ sentry-react-native-stub.js
 | 子路径 | 文件 | 内容 |
 |---|---|---|
 | `.` | `dist/index.js` | `SentryCapture`、`MetroSymbolicator`、全部类型 |
-| `./metro` | `dist/metro.js` | `withDevkit`、`withDevStubs`、`withEntryInjection`、`withExpoNotificationsStub`、`withExpoMediaLibraryStub`、`withExpoCalendarStub` 等 |
+| `./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 |
@@ -297,6 +353,10 @@ sentry-react-native-stub.js
 | `./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 |
 
 ---
@@ -505,6 +565,44 @@ Expo Go 扫码预览不支持访问手机相册
 
 ---
 
+### 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

package/dist/metro.d.mts

@@ -415,6 +415,7 @@ declare function withWasmSupport(config: MetroConfig): MetroConfig;
  *     "bundle_url": "index.bundle",
  *     "initial_build": true,        // true=首次构建 false=增量更新
  *     "graph_node_count": 220,
+ *     "transform_miss_count": 5,    // cache miss 的文件数；0 = 完全命中缓存
  *     "bundle_length": 512000,
  *     "points": {
  *       "resolvingAndTransformingDependencies_start": 5,
@@ -460,6 +461,15 @@ declare function withTransformLogger(config: MetroConfig): MetroConfig;
  *
  * cache key 由文件内容 sha1 + 相对路径 + Babel/Metro 版本共同决定，
  * 与项目绝对路径无关，换目录 clone 后缓存同样有效。
+ *
+ * 若 METRO_TRANSFORM_LOG 已设置，启动时向日志追加一条 CACHE_CONFIG 条目：
+ *   {
+ *     "type": "CACHE_CONFIG",
+ *     "cache_root": "/workspace/.metro-cache",
+ *     "store_class": "ExpoFileStore",    // 生效的 store 类名
+ *     "source": "env" | "option" | "default",
+ *     "t": 1234567890
+ *   }
  */
 
 interface PersistentCacheOptions {

package/dist/metro.d.ts

@@ -415,6 +415,7 @@ declare function withWasmSupport(config: MetroConfig): MetroConfig;
  *     "bundle_url": "index.bundle",
  *     "initial_build": true,        // true=首次构建 false=增量更新
  *     "graph_node_count": 220,
+ *     "transform_miss_count": 5,    // cache miss 的文件数；0 = 完全命中缓存
  *     "bundle_length": 512000,
  *     "points": {
  *       "resolvingAndTransformingDependencies_start": 5,
@@ -460,6 +461,15 @@ declare function withTransformLogger(config: MetroConfig): MetroConfig;
  *
  * cache key 由文件内容 sha1 + 相对路径 + Babel/Metro 版本共同决定，
  * 与项目绝对路径无关，换目录 clone 后缓存同样有效。
+ *
+ * 若 METRO_TRANSFORM_LOG 已设置，启动时向日志追加一条 CACHE_CONFIG 条目：
+ *   {
+ *     "type": "CACHE_CONFIG",
+ *     "cache_root": "/workspace/.metro-cache",
+ *     "store_class": "ExpoFileStore",    // 生效的 store 类名
+ *     "source": "env" | "option" | "default",
+ *     "t": 1234567890
+ *   }
  */
 
 interface PersistentCacheOptions {

package/dist/metro.js

@@ -504,6 +504,7 @@ function withWasmSupport(config) {
 var import_node_fs = __toESM(require("fs"));
 var import_node_path = __toESM(require("path"));
 var import_metro_core = require("metro-core");
+var currentMissCount = 0;
 function installPerfLogger(logFile, existingFactory) {
   const dir = import_node_path.default.dirname(logFile);
   if (!import_node_fs.default.existsSync(dir)) {
@@ -515,6 +516,7 @@ function installPerfLogger(logFile, existingFactory) {
     const startTime = process.hrtime.bigint();
     const points = {};
     const annotations = {};
+    const missCountAtStart = currentMissCount;
     const logger = {
       start() {
         upstream?.start?.();
@@ -526,6 +528,7 @@ function installPerfLogger(logFile, existingFactory) {
           status,
           duration_ms: Math.round(duration_ms),
           ...annotations,
+          transform_miss_count: currentMissCount - missCountAtStart,
           points,
           t: Date.now()
         });
@@ -557,6 +560,7 @@ function installFileLogger(logFile) {
   fileLoggerInstalled = true;
   import_metro_core.Logger.on("log", (entry) => {
     if (entry.action_name === "Transforming file" && entry.action_phase === "end") {
+      currentMissCount++;
       const line = JSON.stringify({
         type: "TRANSFORM_FILE",
         file: entry.file_name,
@@ -580,6 +584,7 @@ function withTransformLogger(config) {
 }
 
 // src/metro/withPersistentCache.ts
+var import_node_fs2 = __toESM(require("fs"));
 var import_path14 = __toESM(require("path"));
 var import_metro_cache = require("metro-cache");
 function withPersistentCache(config, options = {}) {
@@ -597,6 +602,17 @@ function withPersistentCache(config, options = {}) {
   const existingStores = config.cacheStores;
   const firstStore = Array.isArray(existingStores) ? existingStores[0] : void 0;
   const StoreClass = firstStore ? Object.getPrototypeOf(firstStore).constructor : import_metro_cache.FileStore;
+  const logFile = process.env["METRO_TRANSFORM_LOG"];
+  if (logFile) {
+    const line = JSON.stringify({
+      type: "CACHE_CONFIG",
+      cache_root: cacheRoot,
+      store_class: StoreClass.name || "unknown",
+      source: envCacheDir ? "env" : cacheDir ? "option" : "default",
+      t: Date.now()
+    });
+    import_node_fs2.default.appendFileSync(logFile, line + "\n");
+  }
   return {
     ...config,
     cacheStores: [new StoreClass({ root: cacheRoot })]

package/dist/metro.mjs

@@ -455,6 +455,7 @@ function withWasmSupport(config) {
 import fs4 from "fs";
 import path14 from "path";
 import { Logger } from "metro-core";
+var currentMissCount = 0;
 function installPerfLogger(logFile, existingFactory) {
   const dir = path14.dirname(logFile);
   if (!fs4.existsSync(dir)) {
@@ -466,6 +467,7 @@ function installPerfLogger(logFile, existingFactory) {
     const startTime = process.hrtime.bigint();
     const points = {};
     const annotations = {};
+    const missCountAtStart = currentMissCount;
     const logger = {
       start() {
         upstream?.start?.();
@@ -477,6 +479,7 @@ function installPerfLogger(logFile, existingFactory) {
           status,
           duration_ms: Math.round(duration_ms),
           ...annotations,
+          transform_miss_count: currentMissCount - missCountAtStart,
           points,
           t: Date.now()
         });
@@ -508,6 +511,7 @@ function installFileLogger(logFile) {
   fileLoggerInstalled = true;
   Logger.on("log", (entry) => {
     if (entry.action_name === "Transforming file" && entry.action_phase === "end") {
+      currentMissCount++;
       const line = JSON.stringify({
         type: "TRANSFORM_FILE",
         file: entry.file_name,
@@ -531,6 +535,7 @@ function withTransformLogger(config) {
 }
 
 // src/metro/withPersistentCache.ts
+import fs5 from "fs";
 import path15 from "path";
 import { FileStore } from "metro-cache";
 function withPersistentCache(config, options = {}) {
@@ -548,6 +553,17 @@ function withPersistentCache(config, options = {}) {
   const existingStores = config.cacheStores;
   const firstStore = Array.isArray(existingStores) ? existingStores[0] : void 0;
   const StoreClass = firstStore ? Object.getPrototypeOf(firstStore).constructor : FileStore;
+  const logFile = process.env["METRO_TRANSFORM_LOG"];
+  if (logFile) {
+    const line = JSON.stringify({
+      type: "CACHE_CONFIG",
+      cache_root: cacheRoot,
+      store_class: StoreClass.name || "unknown",
+      source: envCacheDir ? "env" : cacheDir ? "option" : "default",
+      t: Date.now()
+    });
+    fs5.appendFileSync(logFile, line + "\n");
+  }
   return {
     ...config,
     cacheStores: [new StoreClass({ root: cacheRoot })]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-expo-devkit",
-  "version": "0.1.1-beta.69",
+  "version": "0.1.1-beta.70",
   "description": "Expo 应用开发工具集：Sentry DSN 替换 stub、错误/网络捕获、Metro 符号化",
   "license": "MIT",
   "main": "./dist/index.js",