miaoda-expo-devkit 0.1.1-beta.25 → 0.1.1-beta.26

package/dist/babel/plugin-lucide-react-native.d.ts

@@ -18,6 +18,12 @@ interface Config extends babelCore.PluginPass {
     opts: {
         /** 使用 ESM 格式（dist/esm）。默认 false，使用 CJS（dist/cjs）。 */
         useES?: boolean;
+        /**
+         * lucide-react-native 包根目录的绝对路径（含 package.json 的那一层）。
+         * 不传时通过 require.resolve 自动定位，适用于生产场景。
+         * 测试时可传入特定版本的路径，验证不同版本的兼容性。
+         */
+        lucidePkgRoot?: string;
     };
 }
 declare function lucideReactNativePlugin({ types: t }: Core): babelCore.PluginObj<Config>;

package/dist/babel/plugin-lucide-react-native.js

@@ -14591,8 +14591,8 @@ var import_node_fs = __toESM(require("fs"));
 var import_node_path = __toESM(require("path"));
 var import_helper_module_imports = __toESM(require_lib4());
 var LUCIDE_REACT_NATIVE = "lucide-react-native";
-function resolveIconsLocation(moduleDir) {
-  const lucideDistPath = import_node_path.default.dirname(import_node_path.default.dirname(require.resolve(LUCIDE_REACT_NATIVE)));
+function resolveIconsLocation(moduleDir, pkgRoot) {
+  const lucideDistPath = pkgRoot ? import_node_path.default.join(pkgRoot, "dist") : import_node_path.default.dirname(import_node_path.default.dirname(require.resolve(LUCIDE_REACT_NATIVE)));
   if (moduleDir === "cjs") {
     const withSubdir = import_node_path.default.join(lucideDistPath, "cjs/icons");
     const hasSubdir = import_node_fs.default.existsSync(withSubdir);
@@ -14611,12 +14611,14 @@ function resolveIconsLocation(moduleDir) {
   };
 }
 var iconMapCache = /* @__PURE__ */ new Map();
-var aliasMap = null;
-function buildAliasMap(moduleDir) {
-  if (aliasMap) return aliasMap;
-  const { map: fileMap } = buildIconMap(moduleDir);
+var aliasMapCache = /* @__PURE__ */ new Map();
+function buildAliasMap(moduleDir, pkgRoot) {
+  const cacheKey = pkgRoot ?? "";
+  const cached = aliasMapCache.get(cacheKey);
+  if (cached) return cached;
+  const { map: fileMap } = buildIconMap(moduleDir, pkgRoot);
   const map = /* @__PURE__ */ new Map();
-  const lucideDistPath = import_node_path.default.dirname(import_node_path.default.dirname(require.resolve(LUCIDE_REACT_NATIVE)));
+  const lucideDistPath = pkgRoot ? import_node_path.default.join(pkgRoot, "dist") : import_node_path.default.dirname(import_node_path.default.dirname(require.resolve(LUCIDE_REACT_NATIVE)));
   const cjsBundle = import_node_path.default.join(lucideDistPath, "cjs/lucide-react-native.js");
   if (import_node_fs.default.existsSync(cjsBundle)) {
     const content = import_node_fs.default.readFileSync(cjsBundle, "utf-8");
@@ -14645,13 +14647,14 @@ function buildAliasMap(moduleDir) {
       }
     }
   }
-  aliasMap = map;
+  aliasMapCache.set(cacheKey, map);
   return map;
 }
-function buildIconMap(moduleDir) {
-  const cached = iconMapCache.get(moduleDir);
+function buildIconMap(moduleDir, pkgRoot) {
+  const cacheKey = `${moduleDir}:${pkgRoot ?? ""}`;
+  const cached = iconMapCache.get(cacheKey);
   if (cached) return cached;
-  const { dir, ext, importBasePath } = resolveIconsLocation(moduleDir);
+  const { dir, ext, importBasePath } = resolveIconsLocation(moduleDir, pkgRoot);
   const map = /* @__PURE__ */ new Map();
   for (const file of import_node_fs.default.readdirSync(dir)) {
     if (!file.endsWith(ext) || file.endsWith(".map")) continue;
@@ -14659,15 +14662,15 @@ function buildIconMap(moduleDir) {
     map.set(slug.replace(/-/g, ""), slug);
   }
   const data = { map, importBasePath };
-  iconMapCache.set(moduleDir, data);
+  iconMapCache.set(cacheKey, data);
   return data;
 }
-function resolveModule(useES, name) {
+function resolveModule(useES, name, pkgRoot) {
   const moduleDir = useES ? "esm" : "cjs";
-  const { map, importBasePath } = buildIconMap(moduleDir);
+  const { map, importBasePath } = buildIconMap(moduleDir, pkgRoot);
   let slug = map.get(name.toLowerCase());
   if (!slug) {
-    const canonical = buildAliasMap(moduleDir).get(name.toLowerCase());
+    const canonical = buildAliasMap(moduleDir, pkgRoot).get(name.toLowerCase());
     if (canonical) {
       slug = map.get(canonical);
     }
@@ -14688,23 +14691,26 @@ function lucideReactNativePlugin({ types: t }) {
   let selectedIcons = /* @__PURE__ */ Object.create(null);
   let specifiedLocal4Imported = /* @__PURE__ */ Object.create(null);
   let removablePaths = [];
-  function importMethod(useES, iconName, nodePath, nameHint) {
+  function importMethod(useES, iconName, nodePath, nameHint, pkgRoot) {
     const existedImport = selectedIcons[iconName];
     if (existedImport) {
       return t.cloneNode(existedImport);
     }
-    const identifier = (0, import_helper_module_imports.addDefault)(nodePath, resolveModule(useES, iconName), { nameHint });
+    const identifier = (0, import_helper_module_imports.addDefault)(nodePath, resolveModule(useES, iconName, pkgRoot), { nameHint });
     selectedIcons[iconName] = identifier;
     return t.cloneNode(identifier);
   }
   function matchesLucideIcon(nodePath, localName) {
-    return specifiedLocal4Imported[localName] && nodePath.scope.hasBinding(localName) && nodePath.scope.getBinding(localName)?.path.type === "ImportSpecifier";
+    if (!specifiedLocal4Imported[localName]) return false;
+    const binding = nodePath.scope.getBinding(localName);
+    if (!binding) return true;
+    return binding.path.type === "ImportSpecifier";
   }
-  function replaceIconRef(nodePath, useES, makeNode) {
+  function replaceIconRef(nodePath, useES, makeNode, pkgRoot) {
     const localName = nodePath.node.name;
     const iconImportedName = specifiedLocal4Imported[localName];
     if (!iconImportedName || !matchesLucideIcon(nodePath, localName) || isSpecialTypes(t, nodePath.parent, nodePath.node)) return;
-    const newNode = importMethod(useES, iconImportedName, nodePath, localName);
+    const newNode = importMethod(useES, iconImportedName, nodePath, localName, pkgRoot);
     nodePath.replaceWith(makeNode(newNode.name, nodePath.node));
   }
   return {
@@ -14742,7 +14748,7 @@ function lucideReactNativePlugin({ types: t }) {
       // 将 re-export 转换为：先插入各图标的默认导入，再导出本地标识符
       ExportNamedDeclaration(nodePath, state) {
         const { node } = nodePath;
-        const { useES = false } = state.opts;
+        const { useES = false, lucidePkgRoot } = state.opts;
         if (!node.source || node.source.value !== LUCIDE_REACT_NATIVE) return;
         const specifiers = [];
         node.specifiers.forEach((spec) => {
@@ -14753,7 +14759,7 @@ function lucideReactNativePlugin({ types: t }) {
           }
           const exportedName = t.isIdentifier(spec.exported) ? spec.exported.name : spec.exported.value;
           const localName = spec.local.name;
-          const importIdentifier = importMethod(useES, localName, nodePath, exportedName);
+          const importIdentifier = importMethod(useES, localName, nodePath, exportedName, lucidePkgRoot);
           specifiers.push(t.exportSpecifier(importIdentifier, t.identifier(exportedName)));
         });
         node.specifiers = specifiers;
@@ -14769,14 +14775,14 @@ function lucideReactNativePlugin({ types: t }) {
       },
       // 处理 JSX 中的图标使用：<Star /> <BookHeart size={24} />
       JSXIdentifier(nodePath, state) {
-        replaceIconRef(nodePath, state.opts.useES ?? false, (name) => t.jsxIdentifier(name));
+        replaceIconRef(nodePath, state.opts.useES ?? false, (name) => t.jsxIdentifier(name), state.opts.lucidePkgRoot);
       },
       // 处理非 JSX 场景中的图标引用：React.createElement(Star)、const icon = Star
       Identifier(nodePath, state) {
         replaceIconRef(nodePath, state.opts.useES ?? false, (name, orig) => ({
           type: orig.type,
           name
-        }));
+        }), state.opts.lucidePkgRoot);
       }
     }
   };

package/dist/metro.d.mts

@@ -58,37 +58,18 @@ declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig
 /**
  * withEntryInjection — 在 expo-router 启动前注入脚本
  *
- * 注入原理：
- *   拦截 Metro 对 expo-router/entry-classic 的解析，将其重定向到
- *   dist/stubs/expo-router-entry-stub.js。stub 先 require entry-inject.js
- *   （注入脚本），再 require expo-router/entry-classic（原入口），
- *   从而在 expo-router 启动前执行注入逻辑。
+ * 拦截 expo-router/entry-classic 的解析，重定向到 expo-router-entry-stub.js。
+ * stub 先 require entry-inject.js，再 require expo-router/entry-classic，
+ * 使注入脚本在 expo-router renderRootComponent 之前执行。
  *
- *   拦截 entry-classic 而非 entry 本身，原因：
- *     - expo-router/entry 以 <script src="...entry.bundle..."> 方式直接加载，
- *       不经过 resolveRequest。
- *     - expo-router/entry 内部第一行是 import 'expo-router/entry-classic'，
- *       这条 import 语句经过 resolveRequest，可以被拦截。
- *
- * 执行顺序（在 bundle 中）：
- *   entry-inject.js → expo-router/entry-classic → renderRootComponent(App)
- *
- * 注入的脚本经过完整 Babel 编译，支持现代语法，web + native 双平台均有效。
- * 支持与 withDevStubs 及其他 Metro wrapper 链式组合。
- *
- * 用法（metro.config.js）：
- *   const { withEntryInjection } = require('miaoda-expo-devkit/metro');
- *   module.exports = withEntryInjection(withDevStubs(config));
+ * 拦截 entry-classic 而非 entry 本身：expo-router/entry 通过 <script src="...entry.bundle">
+ * 直接加载，不经过 resolveRequest；其内部的 import 'expo-router/entry-classic' 才经过 resolveRequest。
  */
 
-/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
 interface InjectOptions {
 }
 /**
- * 在 expo-router 启动前注入一段脚本。
- *
  * @param config  Metro config 对象
- * @param options 注入选项（当前预留，未来支持自定义注入脚本路径）
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withEntryInjection(config: MetroConfig, options?: InjectOptions): MetroConfig;
@@ -129,12 +110,11 @@ declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOp
 /**
  * withDevkit — 一站式 Metro 配置入口
  *
- * 将模板 metro.config.js 所需的所有 devkit wrapper 封装为单个函数调用，
- * 消除模板侧的 boilerplate。内部按固定顺序依次应用：
- *
- *   withWorkspaceNodeModules    — 修复沙箱中 node_modules 不在 projectRoot 内的问题
- *   withCssInterop              — 为 expo-image / expo-camera 注入 NativeWind cssInterop
- *   withLucideResolver          — 消除 lucide 子路径未在 exports 中声明的警告
+ * 按固定顺序依次应用：
+ *   withWorkspaceNodeModules    — 修复沙箱中 node_modules 位于祖先目录时的模块解析问题
+ *   withCssInterop              — 为 expo-image / expo-camera 等注入 NativeWind cssInterop
+ *   withEsbuildMinify           — 将 Metro minifier 切换为 esbuild（仅生产构建生效）
+ *   withLucideResolver          — 消除 lucide 子路径未在 exports 声明时的 warning
  *   withExpoNotificationsStub   — Android：expo-notifications → stub（Expo Go no-op，Dev Build 透传）
  *   withEntryInjection          — 在 expo-router 启动前注入脚本（仅 __DEV__）
  *   withDevStubs                — 替换 Sentry DSN / 屏蔽 LogBox（仅 __DEV__）
@@ -148,14 +128,6 @@ declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOp
  *   module.exports = withDevkit(getDefaultConfig(__dirname));
  */
 
-/**
- * Android 平台：将 expo-notifications 替换为 stub。
- * stub 内部根据 isRunningInExpoGo() 决定是 no-op（Expo Go）还是透传真实模块（Development Build）。
- *
- * 注意：此 wrapper 必须在 if (__DEV__) 外部调用，因为它需要在所有构建模式下生效。
- * Expo Go 中 native module 的缺失是运行时问题，与开发/生产模式无关。
- */
-declare function withExpoNotificationsStub(config: MetroConfig): MetroConfig;
 /** withDevkit 的配置选项 */
 interface DevkitOptions {
     /**
@@ -174,23 +146,14 @@ interface DevkitOptions {
 declare function withDevkit(config: MetroConfig, options?: DevkitOptions): MetroConfig;
 
 /**
- * withDevStubs — Metro resolver 注入开发阶段 stub
+ * withDevStubs — 开发阶段模块替换
  *
- * 注入行为：
- *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
- *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
- *
- * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
- *
- * 用法（metro.config.js）：
- *   const { withDevStubs } = require('miaoda-expo-devkit/metro');
- *   module.exports = withDevStubs(getDefaultConfig(__dirname));
+ * 1. web：@expo/log-box / ErrorOverlayWebControls → no-op stub（屏蔽全屏错误遮罩）
+ * 2. 所有平台：@sentry/react-native → stub（替换 DSN，注入内置捕获器）
  */
 
 /**
- * 将开发阶段 stub 注入到 Metro config 中。
- *
- * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
+ * @param config  Metro config 对象
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withDevStubs(config: MetroConfig): MetroConfig;
@@ -231,37 +194,69 @@ declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
 /**
  * withCssInterop — 为第三方 Expo 组件注入 NativeWind cssInterop
  *
- * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
- * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
- * stub 内部 import 原包时，originModulePath 检查避免循环依赖。
+ * 在 Metro resolver 层拦截目标包的 import，重定向到对应 stub 文件。
+ * stub 透传原包所有导出，并调用 cssInterop 注册 className → style 映射。
+ * stub 内部再次 import 原包时，通过 originModulePath 检查避免循环依赖。
  *
- * 当前支持的包：
- *   - expo-image：Image 组件（className → style）
- *   - expo-camera：CameraView 组件（className → style）
- *   - expo-linear-gradient：LinearGradient 组件（className → style）
- *   - expo-blur：BlurView / BlurTargetView 组件（className → style）
+ * 支持的包：
+ *   - expo-image（Image）
+ *   - expo-camera（CameraView）
+ *   - expo-linear-gradient（LinearGradient）
+ *   - expo-blur（BlurView / BlurTargetView）
  *
- * 注意：react-native-reanimated 不拦截。cssInterop 全局注册 Animated.* 会导致所有动画 style 注入失败。
- * 需要同时使用 Tailwind className 和动画的场景，请在组件层面单独用 createAnimatedComponent + cssInterop 封装。
- *
- * 注意：expo-video 的 VideoView 在 web 上直接渲染 DOM <video> 元素，不经过 RN 样式系统，
- * cssInterop/remapProps 均无效，不做拦截。需要 className 时请用 View 包裹 VideoView。
+ * 不拦截 react-native-reanimated：cssInterop 全局注册 Animated.* 会导致动画 style 注入失败。
+ * 不拦截 expo-video：VideoView 在 web 上直接渲染 DOM <video>，不经过 RN 样式系统。
+ */
+
+/**
+ * @param config  Metro config 对象
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withCssInterop(config: MetroConfig): MetroConfig;
+
+/**
+ * withLucideResolver — 拦截 lucide-react-native 图标子路径导入
  *
- * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
- * 支持与其他 Metro wrapper 链式组合。
+ * babel-plugin-lucide-react-native 会将图标 import 改写为形如
+ * lucide-react-native/dist/cjs/icons/Star 的子路径。
+ * 这些路径未在 package.json exports 中声明，Metro 会报 warning 或解析失败。
  *
- * 用法（metro.config.js）：
- *   const { withCssInterop } = require('miaoda-expo-devkit/metro');
- *   module.exports = withCssInterop(config);
+ * 此 resolver 将这些子路径直接映射到绝对文件路径，绕过 exports 检查。
+ * 扩展名规则：dist/cjs/** → .js，dist/esm/** → .mjs（新版）或 .js（v1.8.x 旧版）
  */
 
+interface WithLucideResolverOptions {
+    /**
+     * lucide-react-native 包根目录的绝对路径。
+     * 不传时通过 require.resolve 自动定位，适用于生产场景。
+     * 测试时可传入特定版本的路径，验证不同版本的兼容性。
+     */
+    lucidePkgRoot?: string;
+}
 /**
- * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ * @param config   Metro config 对象
+ * @param options  可选配置
+ * @returns        注入 resolveRequest 后的新 Metro config
+ */
+declare function withLucideResolver(config: MetroConfig, options?: WithLucideResolverOptions): MetroConfig;
+
+/**
+ * withExpoNotificationsStub — Android 平台将 expo-notifications 替换为 stub
  *
+ * Expo Go 缺少 expo-notifications 所需的 native module，直接 import 会崩溃。
+ * stub 在运行时通过 isRunningInExpoGo() 判断：
+ *   - Expo Go：no-op（所有 API 静默返回空值）
+ *   - Development Build：透传真实 expo-notifications 模块
+ *
+ * 此 wrapper 需要在开发和生产构建中均生效，因为 native module 缺失是运行时问题，
+ * 与 __DEV__ 无关。
+ */
+
+/**
  * @param config  Metro config 对象
  * @returns       注入 resolveRequest 后的新 Metro config
  */
-declare function withCssInterop(config: MetroConfig): MetroConfig;
+declare function withExpoNotificationsStub(config: MetroConfig): MetroConfig;
 
 /**
  * 将 Metro transformer 的 minifier 切换为 esbuild。
@@ -275,4 +270,4 @@ declare function withCssInterop(config: MetroConfig): MetroConfig;
  */
 declare function withEsbuildMinify(config: MetroConfig): MetroConfig;
 
-export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withEsbuildMinify, withExpoNotificationsStub, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };
+export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withEsbuildMinify, withExpoNotificationsStub, withLucideResolver, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };

package/dist/metro.d.ts

@@ -58,37 +58,18 @@ declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig
 /**
  * withEntryInjection — 在 expo-router 启动前注入脚本
  *
- * 注入原理：
- *   拦截 Metro 对 expo-router/entry-classic 的解析，将其重定向到
- *   dist/stubs/expo-router-entry-stub.js。stub 先 require entry-inject.js
- *   （注入脚本），再 require expo-router/entry-classic（原入口），
- *   从而在 expo-router 启动前执行注入逻辑。
+ * 拦截 expo-router/entry-classic 的解析，重定向到 expo-router-entry-stub.js。
+ * stub 先 require entry-inject.js，再 require expo-router/entry-classic，
+ * 使注入脚本在 expo-router renderRootComponent 之前执行。
  *
- *   拦截 entry-classic 而非 entry 本身，原因：
- *     - expo-router/entry 以 <script src="...entry.bundle..."> 方式直接加载，
- *       不经过 resolveRequest。
- *     - expo-router/entry 内部第一行是 import 'expo-router/entry-classic'，
- *       这条 import 语句经过 resolveRequest，可以被拦截。
- *
- * 执行顺序（在 bundle 中）：
- *   entry-inject.js → expo-router/entry-classic → renderRootComponent(App)
- *
- * 注入的脚本经过完整 Babel 编译，支持现代语法，web + native 双平台均有效。
- * 支持与 withDevStubs 及其他 Metro wrapper 链式组合。
- *
- * 用法（metro.config.js）：
- *   const { withEntryInjection } = require('miaoda-expo-devkit/metro');
- *   module.exports = withEntryInjection(withDevStubs(config));
+ * 拦截 entry-classic 而非 entry 本身：expo-router/entry 通过 <script src="...entry.bundle">
+ * 直接加载，不经过 resolveRequest；其内部的 import 'expo-router/entry-classic' 才经过 resolveRequest。
  */
 
-/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
 interface InjectOptions {
 }
 /**
- * 在 expo-router 启动前注入一段脚本。
- *
  * @param config  Metro config 对象
- * @param options 注入选项（当前预留，未来支持自定义注入脚本路径）
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withEntryInjection(config: MetroConfig, options?: InjectOptions): MetroConfig;
@@ -129,12 +110,11 @@ declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOp
 /**
  * withDevkit — 一站式 Metro 配置入口
  *
- * 将模板 metro.config.js 所需的所有 devkit wrapper 封装为单个函数调用，
- * 消除模板侧的 boilerplate。内部按固定顺序依次应用：
- *
- *   withWorkspaceNodeModules    — 修复沙箱中 node_modules 不在 projectRoot 内的问题
- *   withCssInterop              — 为 expo-image / expo-camera 注入 NativeWind cssInterop
- *   withLucideResolver          — 消除 lucide 子路径未在 exports 中声明的警告
+ * 按固定顺序依次应用：
+ *   withWorkspaceNodeModules    — 修复沙箱中 node_modules 位于祖先目录时的模块解析问题
+ *   withCssInterop              — 为 expo-image / expo-camera 等注入 NativeWind cssInterop
+ *   withEsbuildMinify           — 将 Metro minifier 切换为 esbuild（仅生产构建生效）
+ *   withLucideResolver          — 消除 lucide 子路径未在 exports 声明时的 warning
  *   withExpoNotificationsStub   — Android：expo-notifications → stub（Expo Go no-op，Dev Build 透传）
  *   withEntryInjection          — 在 expo-router 启动前注入脚本（仅 __DEV__）
  *   withDevStubs                — 替换 Sentry DSN / 屏蔽 LogBox（仅 __DEV__）
@@ -148,14 +128,6 @@ declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOp
  *   module.exports = withDevkit(getDefaultConfig(__dirname));
  */
 
-/**
- * Android 平台：将 expo-notifications 替换为 stub。
- * stub 内部根据 isRunningInExpoGo() 决定是 no-op（Expo Go）还是透传真实模块（Development Build）。
- *
- * 注意：此 wrapper 必须在 if (__DEV__) 外部调用，因为它需要在所有构建模式下生效。
- * Expo Go 中 native module 的缺失是运行时问题，与开发/生产模式无关。
- */
-declare function withExpoNotificationsStub(config: MetroConfig): MetroConfig;
 /** withDevkit 的配置选项 */
 interface DevkitOptions {
     /**
@@ -174,23 +146,14 @@ interface DevkitOptions {
 declare function withDevkit(config: MetroConfig, options?: DevkitOptions): MetroConfig;
 
 /**
- * withDevStubs — Metro resolver 注入开发阶段 stub
+ * withDevStubs — 开发阶段模块替换
  *
- * 注入行为：
- *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
- *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
- *
- * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
- *
- * 用法（metro.config.js）：
- *   const { withDevStubs } = require('miaoda-expo-devkit/metro');
- *   module.exports = withDevStubs(getDefaultConfig(__dirname));
+ * 1. web：@expo/log-box / ErrorOverlayWebControls → no-op stub（屏蔽全屏错误遮罩）
+ * 2. 所有平台：@sentry/react-native → stub（替换 DSN，注入内置捕获器）
  */
 
 /**
- * 将开发阶段 stub 注入到 Metro config 中。
- *
- * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
+ * @param config  Metro config 对象
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withDevStubs(config: MetroConfig): MetroConfig;
@@ -231,37 +194,69 @@ declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
 /**
  * withCssInterop — 为第三方 Expo 组件注入 NativeWind cssInterop
  *
- * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
- * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
- * stub 内部 import 原包时，originModulePath 检查避免循环依赖。
+ * 在 Metro resolver 层拦截目标包的 import，重定向到对应 stub 文件。
+ * stub 透传原包所有导出，并调用 cssInterop 注册 className → style 映射。
+ * stub 内部再次 import 原包时，通过 originModulePath 检查避免循环依赖。
  *
- * 当前支持的包：
- *   - expo-image：Image 组件（className → style）
- *   - expo-camera：CameraView 组件（className → style）
- *   - expo-linear-gradient：LinearGradient 组件（className → style）
- *   - expo-blur：BlurView / BlurTargetView 组件（className → style）
+ * 支持的包：
+ *   - expo-image（Image）
+ *   - expo-camera（CameraView）
+ *   - expo-linear-gradient（LinearGradient）
+ *   - expo-blur（BlurView / BlurTargetView）
  *
- * 注意：react-native-reanimated 不拦截。cssInterop 全局注册 Animated.* 会导致所有动画 style 注入失败。
- * 需要同时使用 Tailwind className 和动画的场景，请在组件层面单独用 createAnimatedComponent + cssInterop 封装。
- *
- * 注意：expo-video 的 VideoView 在 web 上直接渲染 DOM <video> 元素，不经过 RN 样式系统，
- * cssInterop/remapProps 均无效，不做拦截。需要 className 时请用 View 包裹 VideoView。
+ * 不拦截 react-native-reanimated：cssInterop 全局注册 Animated.* 会导致动画 style 注入失败。
+ * 不拦截 expo-video：VideoView 在 web 上直接渲染 DOM <video>，不经过 RN 样式系统。
+ */
+
+/**
+ * @param config  Metro config 对象
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withCssInterop(config: MetroConfig): MetroConfig;
+
+/**
+ * withLucideResolver — 拦截 lucide-react-native 图标子路径导入
  *
- * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
- * 支持与其他 Metro wrapper 链式组合。
+ * babel-plugin-lucide-react-native 会将图标 import 改写为形如
+ * lucide-react-native/dist/cjs/icons/Star 的子路径。
+ * 这些路径未在 package.json exports 中声明，Metro 会报 warning 或解析失败。
  *
- * 用法（metro.config.js）：
- *   const { withCssInterop } = require('miaoda-expo-devkit/metro');
- *   module.exports = withCssInterop(config);
+ * 此 resolver 将这些子路径直接映射到绝对文件路径，绕过 exports 检查。
+ * 扩展名规则：dist/cjs/** → .js，dist/esm/** → .mjs（新版）或 .js（v1.8.x 旧版）
  */
 
+interface WithLucideResolverOptions {
+    /**
+     * lucide-react-native 包根目录的绝对路径。
+     * 不传时通过 require.resolve 自动定位，适用于生产场景。
+     * 测试时可传入特定版本的路径，验证不同版本的兼容性。
+     */
+    lucidePkgRoot?: string;
+}
 /**
- * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ * @param config   Metro config 对象
+ * @param options  可选配置
+ * @returns        注入 resolveRequest 后的新 Metro config
+ */
+declare function withLucideResolver(config: MetroConfig, options?: WithLucideResolverOptions): MetroConfig;
+
+/**
+ * withExpoNotificationsStub — Android 平台将 expo-notifications 替换为 stub
  *
+ * Expo Go 缺少 expo-notifications 所需的 native module，直接 import 会崩溃。
+ * stub 在运行时通过 isRunningInExpoGo() 判断：
+ *   - Expo Go：no-op（所有 API 静默返回空值）
+ *   - Development Build：透传真实 expo-notifications 模块
+ *
+ * 此 wrapper 需要在开发和生产构建中均生效，因为 native module 缺失是运行时问题，
+ * 与 __DEV__ 无关。
+ */
+
+/**
  * @param config  Metro config 对象
  * @returns       注入 resolveRequest 后的新 Metro config
  */
-declare function withCssInterop(config: MetroConfig): MetroConfig;
+declare function withExpoNotificationsStub(config: MetroConfig): MetroConfig;
 
 /**
  * 将 Metro transformer 的 minifier 切换为 esbuild。
@@ -275,4 +270,4 @@ declare function withCssInterop(config: MetroConfig): MetroConfig;
  */
 declare function withEsbuildMinify(config: MetroConfig): MetroConfig;
 
-export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withEsbuildMinify, withExpoNotificationsStub, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };
+export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withEsbuildMinify, withExpoNotificationsStub, withLucideResolver, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };

package/dist/metro.js

@@ -37,6 +37,7 @@ __export(metro_exports, {
   withEntryInjection: () => withEntryInjection,
   withEsbuildMinify: () => withEsbuildMinify,
   withExpoNotificationsStub: () => withExpoNotificationsStub,
+  withLucideResolver: () => withLucideResolver,
   withNativeWind: () => withNativeWind,
   withRouteEndpoint: () => withRouteEndpoint,
   withWorkspaceNodeModules: () => withWorkspaceNodeModules
@@ -94,9 +95,7 @@ function withDevStubs(config) {
     if (moduleName === "@sentry/react-native" && !context.originModulePath.includes(SENTRY_STUB_FILENAME)) {
       return { filePath: SENTRY_STUB_PATH, type: "sourceFile" };
     }
-    if (upstream) {
-      return upstream(context, moduleName, platform);
-    }
+    if (upstream) return upstream(context, moduleName, platform);
     return context.resolveRequest(context, moduleName, platform);
   };
   return {
@@ -110,8 +109,8 @@ function withDevStubs(config) {
 
 // src/metro/withEntryInjection.ts
 var import_path3 = __toESM(require("path"));
-var EXPO_ROUTER_ENTRY_STUB_PATH = import_path3.default.resolve(__dirname, "stubs", "expo-router-entry-stub.js");
 var EXPO_ROUTER_ENTRY_STUB_FILENAME = "expo-router-entry-stub.js";
+var EXPO_ROUTER_ENTRY_STUB_PATH = import_path3.default.resolve(__dirname, "stubs", EXPO_ROUTER_ENTRY_STUB_FILENAME);
 function withEntryInjection(config, options) {
   void options;
   const upstream = config.resolver?.resolveRequest ?? null;
@@ -284,8 +283,7 @@ function withCssInterop(config) {
 }
 
 // src/metro/withDevkit.ts
-var import_fs3 = __toESM(require("fs"));
-var import_path7 = __toESM(require("path"));
+var import_path9 = __toESM(require("path"));
 
 // src/metro/withEsbuildMinify.ts
 function withEsbuildMinify(config) {
@@ -300,19 +298,21 @@ function withEsbuildMinify(config) {
   };
 }
 
-// src/metro/withDevkit.ts
+// src/metro/withLucideResolver.ts
+var import_fs3 = __toESM(require("fs"));
+var import_path7 = __toESM(require("path"));
 var LUCIDE_PKG = "lucide-react-native";
 var LUCIDE_DIST_PREFIX = `${LUCIDE_PKG}/dist/`;
-var lucidePkgRoot = null;
+var _lucidePkgRoot = null;
 function getLucidePkgRoot() {
-  if (lucidePkgRoot) return lucidePkgRoot;
+  if (_lucidePkgRoot) return _lucidePkgRoot;
   let dir = import_path7.default.dirname(require.resolve(LUCIDE_PKG));
   while (true) {
     const pkgJson = import_path7.default.join(dir, "package.json");
     if (import_fs3.default.existsSync(pkgJson)) {
       const { name } = require(pkgJson);
       if (name === LUCIDE_PKG) {
-        lucidePkgRoot = dir;
+        _lucidePkgRoot = dir;
         return dir;
       }
     }
@@ -321,13 +321,23 @@ function getLucidePkgRoot() {
     dir = parent;
   }
 }
-function withLucideResolver(config) {
+var esmExtCache = /* @__PURE__ */ new Map();
+function getEsmExt(pkgRoot) {
+  const cached = esmExtCache.get(pkgRoot);
+  if (cached) return cached;
+  const esmIconsDir = import_path7.default.join(pkgRoot, "dist/esm/icons");
+  const ext = import_fs3.default.existsSync(esmIconsDir) && import_fs3.default.readdirSync(esmIconsDir).some((f) => f.endsWith(".mjs")) ? ".mjs" : ".js";
+  esmExtCache.set(pkgRoot, ext);
+  return ext;
+}
+function withLucideResolver(config, options = {}) {
   const upstream = config.resolver?.resolveRequest ?? null;
+  const pkgRoot = options.lucidePkgRoot ?? getLucidePkgRoot();
   const resolveRequest = (context, moduleName, platform) => {
     if (moduleName.startsWith(LUCIDE_DIST_PREFIX)) {
       const subpath = moduleName.slice(LUCIDE_PKG.length + 1);
-      const ext = subpath.startsWith("dist/esm/") ? ".mjs" : ".js";
-      const filePath = import_path7.default.join(getLucidePkgRoot(), subpath + ext);
+      const ext = subpath.startsWith("dist/esm/") ? getEsmExt(pkgRoot) : ".js";
+      const filePath = import_path7.default.join(pkgRoot, subpath + ext);
       return { filePath, type: "sourceFile" };
     }
     if (upstream) return upstream(context, moduleName, platform);
@@ -335,8 +345,11 @@ function withLucideResolver(config) {
   };
   return { ...config, resolver: { ...config.resolver, resolveRequest } };
 }
+
+// src/metro/withExpoNotificationsStub.ts
+var import_path8 = __toESM(require("path"));
 var EXPO_NOTIFICATIONS_STUB_FILENAME = "expo-notifications-stub.js";
-var EXPO_NOTIFICATIONS_STUB_PATH = import_path7.default.resolve(__dirname, "stubs", EXPO_NOTIFICATIONS_STUB_FILENAME);
+var EXPO_NOTIFICATIONS_STUB_PATH = import_path8.default.resolve(__dirname, "stubs", EXPO_NOTIFICATIONS_STUB_FILENAME);
 function withExpoNotificationsStub(config) {
   const upstream = config.resolver?.resolveRequest ?? null;
   const resolveRequest = (context, moduleName, platform) => {
@@ -348,6 +361,8 @@ function withExpoNotificationsStub(config) {
   };
   return { ...config, resolver: { ...config.resolver, resolveRequest } };
 }
+
+// src/metro/withDevkit.ts
 function withDevkit(config, options = {}) {
   const projectRoot = config.projectRoot ?? process.cwd();
   const { input = "./src/global.css" } = options;
@@ -359,7 +374,7 @@ function withDevkit(config, options = {}) {
   if (typeof __DEV__ !== "undefined" && __DEV__) {
     config = withEntryInjection(config);
     config = withDevStubs(config);
-    config = withRouteEndpoint(config, { appDir: import_path7.default.join(projectRoot, "src", "app") });
+    config = withRouteEndpoint(config, { appDir: import_path9.default.join(projectRoot, "src", "app") });
   }
   return withNativeWind(config, { input, inlineRem: 16 });
 }
@@ -380,6 +395,7 @@ try {
   withEntryInjection,
   withEsbuildMinify,
   withExpoNotificationsStub,
+  withLucideResolver,
   withNativeWind,
   withRouteEndpoint,
   withWorkspaceNodeModules

package/dist/metro.mjs

@@ -56,9 +56,7 @@ function withDevStubs(config) {
     if (moduleName === "@sentry/react-native" && !context.originModulePath.includes(SENTRY_STUB_FILENAME)) {
       return { filePath: SENTRY_STUB_PATH, type: "sourceFile" };
     }
-    if (upstream) {
-      return upstream(context, moduleName, platform);
-    }
+    if (upstream) return upstream(context, moduleName, platform);
     return context.resolveRequest(context, moduleName, platform);
   };
   return {
@@ -72,8 +70,8 @@ function withDevStubs(config) {
 
 // src/metro/withEntryInjection.ts
 import path3 from "path";
-var EXPO_ROUTER_ENTRY_STUB_PATH = path3.resolve(__dirname, "stubs", "expo-router-entry-stub.js");
 var EXPO_ROUTER_ENTRY_STUB_FILENAME = "expo-router-entry-stub.js";
+var EXPO_ROUTER_ENTRY_STUB_PATH = path3.resolve(__dirname, "stubs", EXPO_ROUTER_ENTRY_STUB_FILENAME);
 function withEntryInjection(config, options) {
   void options;
   const upstream = config.resolver?.resolveRequest ?? null;
@@ -246,8 +244,7 @@ function withCssInterop(config) {
 }
 
 // src/metro/withDevkit.ts
-import fs3 from "fs";
-import path7 from "path";
+import path9 from "path";
 
 // src/metro/withEsbuildMinify.ts
 function withEsbuildMinify(config) {
@@ -262,19 +259,21 @@ function withEsbuildMinify(config) {
   };
 }
 
-// src/metro/withDevkit.ts
+// src/metro/withLucideResolver.ts
+import fs3 from "fs";
+import path7 from "path";
 var LUCIDE_PKG = "lucide-react-native";
 var LUCIDE_DIST_PREFIX = `${LUCIDE_PKG}/dist/`;
-var lucidePkgRoot = null;
+var _lucidePkgRoot = null;
 function getLucidePkgRoot() {
-  if (lucidePkgRoot) return lucidePkgRoot;
+  if (_lucidePkgRoot) return _lucidePkgRoot;
   let dir = path7.dirname(__require.resolve(LUCIDE_PKG));
   while (true) {
     const pkgJson = path7.join(dir, "package.json");
     if (fs3.existsSync(pkgJson)) {
       const { name } = __require(pkgJson);
       if (name === LUCIDE_PKG) {
-        lucidePkgRoot = dir;
+        _lucidePkgRoot = dir;
         return dir;
       }
     }
@@ -283,13 +282,23 @@ function getLucidePkgRoot() {
     dir = parent;
   }
 }
-function withLucideResolver(config) {
+var esmExtCache = /* @__PURE__ */ new Map();
+function getEsmExt(pkgRoot) {
+  const cached = esmExtCache.get(pkgRoot);
+  if (cached) return cached;
+  const esmIconsDir = path7.join(pkgRoot, "dist/esm/icons");
+  const ext = fs3.existsSync(esmIconsDir) && fs3.readdirSync(esmIconsDir).some((f) => f.endsWith(".mjs")) ? ".mjs" : ".js";
+  esmExtCache.set(pkgRoot, ext);
+  return ext;
+}
+function withLucideResolver(config, options = {}) {
   const upstream = config.resolver?.resolveRequest ?? null;
+  const pkgRoot = options.lucidePkgRoot ?? getLucidePkgRoot();
   const resolveRequest = (context, moduleName, platform) => {
     if (moduleName.startsWith(LUCIDE_DIST_PREFIX)) {
       const subpath = moduleName.slice(LUCIDE_PKG.length + 1);
-      const ext = subpath.startsWith("dist/esm/") ? ".mjs" : ".js";
-      const filePath = path7.join(getLucidePkgRoot(), subpath + ext);
+      const ext = subpath.startsWith("dist/esm/") ? getEsmExt(pkgRoot) : ".js";
+      const filePath = path7.join(pkgRoot, subpath + ext);
       return { filePath, type: "sourceFile" };
     }
     if (upstream) return upstream(context, moduleName, platform);
@@ -297,8 +306,11 @@ function withLucideResolver(config) {
   };
   return { ...config, resolver: { ...config.resolver, resolveRequest } };
 }
+
+// src/metro/withExpoNotificationsStub.ts
+import path8 from "path";
 var EXPO_NOTIFICATIONS_STUB_FILENAME = "expo-notifications-stub.js";
-var EXPO_NOTIFICATIONS_STUB_PATH = path7.resolve(__dirname, "stubs", EXPO_NOTIFICATIONS_STUB_FILENAME);
+var EXPO_NOTIFICATIONS_STUB_PATH = path8.resolve(__dirname, "stubs", EXPO_NOTIFICATIONS_STUB_FILENAME);
 function withExpoNotificationsStub(config) {
   const upstream = config.resolver?.resolveRequest ?? null;
   const resolveRequest = (context, moduleName, platform) => {
@@ -310,6 +322,8 @@ function withExpoNotificationsStub(config) {
   };
   return { ...config, resolver: { ...config.resolver, resolveRequest } };
 }
+
+// src/metro/withDevkit.ts
 function withDevkit(config, options = {}) {
   const projectRoot = config.projectRoot ?? process.cwd();
   const { input = "./src/global.css" } = options;
@@ -321,7 +335,7 @@ function withDevkit(config, options = {}) {
   if (typeof __DEV__ !== "undefined" && __DEV__) {
     config = withEntryInjection(config);
     config = withDevStubs(config);
-    config = withRouteEndpoint(config, { appDir: path7.join(projectRoot, "src", "app") });
+    config = withRouteEndpoint(config, { appDir: path9.join(projectRoot, "src", "app") });
   }
   return withNativeWind(config, { input, inlineRem: 16 });
 }
@@ -341,6 +355,7 @@ export {
   withEntryInjection,
   withEsbuildMinify,
   withExpoNotificationsStub,
+  withLucideResolver,
   withNativeWind,
   withRouteEndpoint,
   withWorkspaceNodeModules

package/package.json

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