miaoda-expo-devkit 0.1.1-beta.5 → 0.1.1-beta.7

package/dist/metro.d.mts

@@ -1,52 +1,66 @@
 import { MetroConfig } from 'metro-config';
 
 /**
- * miaoda-expo-devkit/metro
+ * withNativeWind / patchNativeWindCachePath — NativeWind 缓存路径修复与 lazy wrapper
  *
- * 提供 Metro 配置增强函数：
- *   - withDevStubs(config)        模块替换：Sentry DSN 覆盖、LogBox 屏蔽
- *   - withEntryInjection(config)  bundle 首部脚本注入
- *   - withRouteEndpoint(config)   添加 /__routes 端点，返回路由树 JSON
- *   - withWorkspaceNodeModules(config)  修复 node_modules 位于项目父级目录时的资源加载 500 问题
+ * patchNativeWindCachePath：
+ *   将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
+ *   ⚠️ 必须在 require('nativewind/metro') 之前调用，否则 outputDirectory 已经固化，patch 无效。
+ *
+ * withNativeWind：
+ *   nativewind/metro 的 lazy wrapper，确保 nativewind 在 patchNativeWindCachePath 之后加载，
+ *   拿到已 patch 的 outputDirectory。用法与 nativewind 官方 withNativeWind 完全相同。
  *
  * 用法（metro.config.js）：
+ *   const { withNativeWind } = require('miaoda-expo-devkit/metro');
+ *   // 不再需要单独 require('nativewind/metro')
+ *   module.exports = withNativeWind(config, { input: './global.css' });
+ */
+
+/** patchNativeWindCachePath 的配置选项 */
+interface PatchNativeWindCacheOptions {
+    /**
+     * 缓存目录，相对于 process.cwd()（Metro 项目根目录），默认 .native-wind-cache。
+     * 与 package.json 同级，避免写入只读的 node_modules。
+     */
+    cacheDir?: string;
+}
+/**
+ * 将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
  *
- *   const { getDefaultConfig } = require('expo/metro-config');
- *   const { withDevStubs, withEntryInjection, withRouteEndpoint } = require('miaoda-expo-devkit/metro');
+ * ⚠️ 必须在 require('nativewind/metro') / require('react-native-css-interop/dist/metro')
+ * 之前调用，否则 outputDirectory 已经固化，patch 无效。
  *
- *   const config = getDefaultConfig(__dirname);
- *   module.exports = withRouteEndpoint(
- *     withEntryInjection(withDevStubs(config)),
- *     { appDir: path.join(__dirname, 'src', 'app') }
- *   );
+ * 原理：react-native-css-interop/dist/metro 在模块顶层用
+ *   const outputDirectory = path.resolve(__dirname, "../../.cache")
+ * 计算缓存路径。通过在 require 前临时替换 path.resolve，可将该值重定向到
+ * 项目根目录下的自定义缓存目录，而无需 fork 或修改 node_modules 源码。
  *
- * 链式用法（与其他 Metro wrapper 组合）：
+ * ⚠️ 已知限制：依赖 react-native-css-interop 使用 path.resolve 计算缓存路径，
+ * 升级该依赖时需确认此假设仍然成立。
  *
- *   module.exports = withNativeWind(withEntryInjection(withDevStubs(config)), { input: './global.css' });
+ * @param options 配置选项
  */
-
+declare function patchNativeWindCachePath(options?: PatchNativeWindCacheOptions): void;
 /**
- * 将开发阶段 stub 注入到 Metro config 中。
- *
- * 注入行为：
- *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
- *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
+ * withNativeWind 的 lazy wrapper。
  *
- * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
+ * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
+ * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
+ * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
+ * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
  *
- * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
- * @returns       注入 resolveRequest 后的新 Metro config
+ * @param config  Metro config 对象
+ * @param options nativewind withNativeWind 选项（与原包 API 完全一致）
  */
-declare function withDevStubs(config: MetroConfig): MetroConfig;
-/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
-interface InjectOptions {
-}
+declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig;
+
 /**
- * 在 expo-router 启动前注入一段脚本。
+ * withEntryInjection — 在 expo-router 启动前注入脚本
  *
  * 注入原理：
  *   拦截 Metro 对 expo-router/entry-classic 的解析，将其重定向到
- *   dist/stubs/expo-router-entry-stub.js。expo-router-entry-stub.js 先 require entry-inject.js
+ *   dist/stubs/expo-router-entry-stub.js。stub 先 require entry-inject.js
  *   （注入脚本），再 require expo-router/entry-classic（原入口），
  *   从而在 expo-router 启动前执行注入逻辑。
  *
@@ -57,20 +71,46 @@ interface InjectOptions {
  *       这条 import 语句经过 resolveRequest，可以被拦截。
  *
  * 执行顺序（在 bundle 中）：
- *   entry-inject.js（注入脚本：设置 __DEVKIT_INJECTED__ + 安装 HMR 控制器）
- *   → expo-router/entry-classic（原 expo-router 入口）
- *   → renderRootComponent(App)
+ *   entry-inject.js → expo-router/entry-classic → renderRootComponent(App)
  *
  * 注入的脚本经过完整 Babel 编译，支持现代语法，web + native 双平台均有效。
+ * 支持与 withDevStubs 及其他 Metro wrapper 链式组合。
  *
- * 支持与 withDevStubs 及其他 Metro wrapper 链式组合：
+ * 用法（metro.config.js）：
+ *   const { withEntryInjection } = require('miaoda-expo-devkit/metro');
  *   module.exports = withEntryInjection(withDevStubs(config));
+ */
+
+/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
+interface InjectOptions {
+}
+/**
+ * 在 expo-router 启动前注入一段脚本。
  *
  * @param config  Metro config 对象
  * @param options 注入选项（当前预留，未来支持自定义注入脚本路径）
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withEntryInjection(config: MetroConfig, options?: InjectOptions): MetroConfig;
+
+/**
+ * withRouteEndpoint — 为 Metro server 添加路由树查询端点
+ *
+ * 端点（默认 /__routes）返回 JSON 格式的路由树：
+ *   {
+ *     "routes": [
+ *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "src/app/index.tsx" },
+ *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "src/app/user/[id].tsx" }
+ *     ]
+ *   }
+ *
+ * 用法（metro.config.js）：
+ *   const { withRouteEndpoint } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withRouteEndpoint(config, {
+ *     appDir: path.join(__dirname, 'src', 'app'),
+ *   });
+ */
+
 /** withRouteEndpoint 的配置选项 */
 interface RouteEndpointOptions {
     /** app 目录的绝对路径（包含路由文件的目录） */
@@ -81,41 +121,98 @@ interface RouteEndpointOptions {
 /**
  * 为 Metro server 添加 /__routes 端点，返回路由树 JSON。
  *
- * 端点返回格式：
- *   {
- *     "routes": [
- *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "src/app/index.tsx" },
- *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "src/app/user/[id].tsx" }
- *     ]
- *   }
- *
  * @param config  Metro config 对象
  * @param options 配置选项，必须提供 appDir
  * @returns       增强 server.enhanceMiddleware 后的新 Metro config
  */
 declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOptions): MetroConfig;
+
+/**
+ * withDevkit — 一站式 Metro 配置入口
+ *
+ * 将模板 metro.config.js 所需的所有 devkit wrapper 封装为单个函数调用，
+ * 消除模板侧的 boilerplate。内部按固定顺序依次应用：
+ *
+ *   withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内的问题
+ *   withCssInterop           — 为 expo-image / expo-camera 注入 NativeWind cssInterop
+ *   withEntryInjection       — 在 expo-router 启动前注入脚本（仅 __DEV__）
+ *   withDevStubs             — 替换 Sentry DSN / 屏蔽 LogBox（仅 __DEV__）
+ *   withRouteEndpoint        — 添加 /__routes 端点（仅 __DEV__）
+ *   withNativeWind           — NativeWind 支持（含缓存路径修复）
+ *
+ * 用法（metro.config.js）：
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withDevkit } = require('miaoda-expo-devkit/metro');
+ *
+ *   module.exports = withDevkit(getDefaultConfig(__dirname));
+ */
+
+/** withDevkit 的配置选项 */
+interface DevkitOptions {
+    /**
+     * NativeWind 的 CSS 入口文件路径（相对于 projectRoot）。
+     * 默认：'./src/global.css'
+     */
+    input?: string;
+}
+/**
+ * 一站式应用所有 devkit Metro wrapper。
+ *
+ * @param config  Metro config 对象（来自 getDefaultConfig）
+ * @param options 配置选项
+ * @returns       完整配置后的 Metro config
+ */
+declare function withDevkit(config: MetroConfig, options?: DevkitOptions): MetroConfig;
+
+/**
+ * withDevStubs — Metro resolver 注入开发阶段 stub
+ *
+ * 注入行为：
+ *   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));
+ */
+
+/**
+ * 将开发阶段 stub 注入到 Metro config 中。
+ *
+ * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withDevStubs(config: MetroConfig): MetroConfig;
+
 /**
- * 修复沙箱环境中 node_modules 位于项目父级目录时，资源文件（字体、图片等）加载返回 500 的问题。
+ * withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内时的模块解析问题
+ *
+ * 适用场景：node_modules 位于 projectRoot 的祖先目录（如 /workspace/node_modules），
+ * 而 projectRoot 自身的 node_modules 为空目录或不存在。
  *
- * 问题根因：
- *   pnpm 在沙箱中将 node_modules 安装到 projectRoot 的上层目录（如 /workspace/node_modules），
- *   而非 projectRoot 内（如 /workspace/app/node_modules）。
- *   Metro 处理 /assets/?unstable_path=./node_modules/.pnpm/... 请求时，会将路径解析为
- *   path.resolve(projectRoot, './node_modules/.pnpm/...')，得到一个不存在的路径，返回 500。
- *   实际文件在父级的 node_modules/.pnpm/ 下。
+ * 问题：Metro 只监听 projectRoot，不会自动爬取祖先目录的 node_modules，
+ *   导致 Metro 无法在 file map 中找到依赖的真实路径，bundle 请求返回 404。
  *
- * 修复方式：
- *   向上查找实际的 node_modules 目录，将其加入 watchFolders（让 Metro 索引其中的文件）
- *   和 resolver.nodeModulesPaths（让模块解析也能找到包）。
+ * 修复：将祖先目录中的 node_modules 加入 watchFolders 和 resolver.nodeModulesPaths，
+ *   使 Metro 能正确索引并解析其中的模块。
  *
- *   如果 node_modules 就在 projectRoot 下，则不做任何修改，直接返回原始 config。
+ * 用法（metro.config.js）：
+ *   const { withWorkspaceNodeModules } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withWorkspaceNodeModules(config);
+ */
+
+/**
+ * 修复沙箱环境中 node_modules 位于祖先目录时，Metro 模块解析和 bundle 请求失败的问题。
  *
  * @param config  Metro config 对象（来自 getDefaultConfig）
- * @returns       修正 watchFolders 和 nodeModulesPaths 后的新 Metro config
+ * @returns       修正 watchFolders、nodeModulesPaths 后的新 Metro config
  */
 declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
+
 /**
- * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ * withCssInterop — 为第三方 Expo 组件注入 NativeWind cssInterop
  *
  * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
  * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
@@ -128,53 +225,17 @@ declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
  * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
  * 支持与其他 Metro wrapper 链式组合。
  *
- * @param config  Metro config 对象
- * @returns       注入 resolveRequest 后的新 Metro config
- */
-declare function withCssInterop(config: MetroConfig): MetroConfig;
-/** patchNativeWindCachePath 的配置选项 */
-interface PatchNativeWindCacheOptions {
-    /**
-     * 缓存目录，相对于 process.cwd()（Metro 项目根目录），默认 .native-wind-cache。
-     * 与 package.json 同级，避免写入只读的 node_modules。
-     */
-    cacheDir?: string;
-}
-/**
- * 将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
- *
- * ⚠️ 必须在 require('nativewind/metro') / require('react-native-css-interop/dist/metro')
- * 之前调用，否则 outputDirectory 已经固化，patch 无效。
- *
- * 原理：react-native-css-interop/dist/metro 在模块顶层用
- *   const outputDirectory = path.resolve(__dirname, "../../.cache")
- * 计算缓存路径。通过在 require 前临时替换 path.resolve，可将该值重定向到
- * 项目根目录下的自定义缓存目录，而无需 fork 或修改 node_modules 源码。
- *
- * 所有依赖 outputDirectory 的 NativeWind 行为（文件写入、虚拟模块 Map key、
- * Metro resolver 返回值、haste 事件）都会一致使用新路径，无需额外 Metro 层面的 patch。
- *
- * ⚠️ 已知限制：依赖 react-native-css-interop 使用 path.resolve 计算缓存路径，
- * 升级该依赖时需确认此假设仍然成立。
- *
  * 用法（metro.config.js）：
- *   const { patchNativeWindCachePath } = require('miaoda-expo-devkit/metro');
- *   patchNativeWindCachePath(); // 必须在 require nativewind/metro 之前调用
- *   const { withNativeWind } = require('nativewind/metro');
+ *   const { withCssInterop } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withCssInterop(config);
  */
-declare function patchNativeWindCachePath(options?: PatchNativeWindCacheOptions): void;
+
 /**
- * withNativeWind 的 lazy wrapper。
- *
- * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
- * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
- * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
- * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
+ * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
  *
- * 用法（metro.config.js）：
- *   const { withNativeWind } = require('miaoda-expo-devkit/metro');
- *   // 不再需要 require('nativewind/metro')
+ * @param config  Metro config 对象
+ * @returns       注入 resolveRequest 后的新 Metro config
  */
-declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig;
+declare function withCssInterop(config: MetroConfig): MetroConfig;
 
-export { type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withEntryInjection, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };
+export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };

package/dist/metro.d.ts

@@ -1,52 +1,66 @@
 import { MetroConfig } from 'metro-config';
 
 /**
- * miaoda-expo-devkit/metro
+ * withNativeWind / patchNativeWindCachePath — NativeWind 缓存路径修复与 lazy wrapper
  *
- * 提供 Metro 配置增强函数：
- *   - withDevStubs(config)        模块替换：Sentry DSN 覆盖、LogBox 屏蔽
- *   - withEntryInjection(config)  bundle 首部脚本注入
- *   - withRouteEndpoint(config)   添加 /__routes 端点，返回路由树 JSON
- *   - withWorkspaceNodeModules(config)  修复 node_modules 位于项目父级目录时的资源加载 500 问题
+ * patchNativeWindCachePath：
+ *   将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
+ *   ⚠️ 必须在 require('nativewind/metro') 之前调用，否则 outputDirectory 已经固化，patch 无效。
+ *
+ * withNativeWind：
+ *   nativewind/metro 的 lazy wrapper，确保 nativewind 在 patchNativeWindCachePath 之后加载，
+ *   拿到已 patch 的 outputDirectory。用法与 nativewind 官方 withNativeWind 完全相同。
  *
  * 用法（metro.config.js）：
+ *   const { withNativeWind } = require('miaoda-expo-devkit/metro');
+ *   // 不再需要单独 require('nativewind/metro')
+ *   module.exports = withNativeWind(config, { input: './global.css' });
+ */
+
+/** patchNativeWindCachePath 的配置选项 */
+interface PatchNativeWindCacheOptions {
+    /**
+     * 缓存目录，相对于 process.cwd()（Metro 项目根目录），默认 .native-wind-cache。
+     * 与 package.json 同级，避免写入只读的 node_modules。
+     */
+    cacheDir?: string;
+}
+/**
+ * 将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
  *
- *   const { getDefaultConfig } = require('expo/metro-config');
- *   const { withDevStubs, withEntryInjection, withRouteEndpoint } = require('miaoda-expo-devkit/metro');
+ * ⚠️ 必须在 require('nativewind/metro') / require('react-native-css-interop/dist/metro')
+ * 之前调用，否则 outputDirectory 已经固化，patch 无效。
  *
- *   const config = getDefaultConfig(__dirname);
- *   module.exports = withRouteEndpoint(
- *     withEntryInjection(withDevStubs(config)),
- *     { appDir: path.join(__dirname, 'src', 'app') }
- *   );
+ * 原理：react-native-css-interop/dist/metro 在模块顶层用
+ *   const outputDirectory = path.resolve(__dirname, "../../.cache")
+ * 计算缓存路径。通过在 require 前临时替换 path.resolve，可将该值重定向到
+ * 项目根目录下的自定义缓存目录，而无需 fork 或修改 node_modules 源码。
  *
- * 链式用法（与其他 Metro wrapper 组合）：
+ * ⚠️ 已知限制：依赖 react-native-css-interop 使用 path.resolve 计算缓存路径，
+ * 升级该依赖时需确认此假设仍然成立。
  *
- *   module.exports = withNativeWind(withEntryInjection(withDevStubs(config)), { input: './global.css' });
+ * @param options 配置选项
  */
-
+declare function patchNativeWindCachePath(options?: PatchNativeWindCacheOptions): void;
 /**
- * 将开发阶段 stub 注入到 Metro config 中。
- *
- * 注入行为：
- *   1. web 平台：@expo/log-box 及 ErrorOverlayWebControls → no-op-logbox stub（屏蔽全屏错误遮罩）
- *   2. 所有平台：@sentry/react-native → sentry-react-native-stub（替换 DSN，注入内置捕获器）
+ * withNativeWind 的 lazy wrapper。
  *
- * 自动保留并调用已有的 resolveRequest，支持与其他 Metro 配置链式组合。
+ * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
+ * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
+ * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
+ * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
  *
- * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
- * @returns       注入 resolveRequest 后的新 Metro config
+ * @param config  Metro config 对象
+ * @param options nativewind withNativeWind 选项（与原包 API 完全一致）
  */
-declare function withDevStubs(config: MetroConfig): MetroConfig;
-/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
-interface InjectOptions {
-}
+declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig;
+
 /**
- * 在 expo-router 启动前注入一段脚本。
+ * withEntryInjection — 在 expo-router 启动前注入脚本
  *
  * 注入原理：
  *   拦截 Metro 对 expo-router/entry-classic 的解析，将其重定向到
- *   dist/stubs/expo-router-entry-stub.js。expo-router-entry-stub.js 先 require entry-inject.js
+ *   dist/stubs/expo-router-entry-stub.js。stub 先 require entry-inject.js
  *   （注入脚本），再 require expo-router/entry-classic（原入口），
  *   从而在 expo-router 启动前执行注入逻辑。
  *
@@ -57,20 +71,46 @@ interface InjectOptions {
  *       这条 import 语句经过 resolveRequest，可以被拦截。
  *
  * 执行顺序（在 bundle 中）：
- *   entry-inject.js（注入脚本：设置 __DEVKIT_INJECTED__ + 安装 HMR 控制器）
- *   → expo-router/entry-classic（原 expo-router 入口）
- *   → renderRootComponent(App)
+ *   entry-inject.js → expo-router/entry-classic → renderRootComponent(App)
  *
  * 注入的脚本经过完整 Babel 编译，支持现代语法，web + native 双平台均有效。
+ * 支持与 withDevStubs 及其他 Metro wrapper 链式组合。
  *
- * 支持与 withDevStubs 及其他 Metro wrapper 链式组合：
+ * 用法（metro.config.js）：
+ *   const { withEntryInjection } = require('miaoda-expo-devkit/metro');
  *   module.exports = withEntryInjection(withDevStubs(config));
+ */
+
+/** withEntryInjection 的配置选项（预留，供未来支持自定义注入脚本路径扩展） */
+interface InjectOptions {
+}
+/**
+ * 在 expo-router 启动前注入一段脚本。
  *
  * @param config  Metro config 对象
  * @param options 注入选项（当前预留，未来支持自定义注入脚本路径）
  * @returns       注入 resolveRequest 后的新 Metro config
  */
 declare function withEntryInjection(config: MetroConfig, options?: InjectOptions): MetroConfig;
+
+/**
+ * withRouteEndpoint — 为 Metro server 添加路由树查询端点
+ *
+ * 端点（默认 /__routes）返回 JSON 格式的路由树：
+ *   {
+ *     "routes": [
+ *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "src/app/index.tsx" },
+ *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "src/app/user/[id].tsx" }
+ *     ]
+ *   }
+ *
+ * 用法（metro.config.js）：
+ *   const { withRouteEndpoint } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withRouteEndpoint(config, {
+ *     appDir: path.join(__dirname, 'src', 'app'),
+ *   });
+ */
+
 /** withRouteEndpoint 的配置选项 */
 interface RouteEndpointOptions {
     /** app 目录的绝对路径（包含路由文件的目录） */
@@ -81,41 +121,98 @@ interface RouteEndpointOptions {
 /**
  * 为 Metro server 添加 /__routes 端点，返回路由树 JSON。
  *
- * 端点返回格式：
- *   {
- *     "routes": [
- *       { "title": "首页", "pageId": "/", "pageName": "index", "visible": true, "path": "src/app/index.tsx" },
- *       { "title": "id", "pageId": "/user/[id]", "pageName": "user-[id]", "visible": false, "path": "src/app/user/[id].tsx" }
- *     ]
- *   }
- *
  * @param config  Metro config 对象
  * @param options 配置选项，必须提供 appDir
  * @returns       增强 server.enhanceMiddleware 后的新 Metro config
  */
 declare function withRouteEndpoint(config: MetroConfig, options: RouteEndpointOptions): MetroConfig;
+
+/**
+ * withDevkit — 一站式 Metro 配置入口
+ *
+ * 将模板 metro.config.js 所需的所有 devkit wrapper 封装为单个函数调用，
+ * 消除模板侧的 boilerplate。内部按固定顺序依次应用：
+ *
+ *   withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内的问题
+ *   withCssInterop           — 为 expo-image / expo-camera 注入 NativeWind cssInterop
+ *   withEntryInjection       — 在 expo-router 启动前注入脚本（仅 __DEV__）
+ *   withDevStubs             — 替换 Sentry DSN / 屏蔽 LogBox（仅 __DEV__）
+ *   withRouteEndpoint        — 添加 /__routes 端点（仅 __DEV__）
+ *   withNativeWind           — NativeWind 支持（含缓存路径修复）
+ *
+ * 用法（metro.config.js）：
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withDevkit } = require('miaoda-expo-devkit/metro');
+ *
+ *   module.exports = withDevkit(getDefaultConfig(__dirname));
+ */
+
+/** withDevkit 的配置选项 */
+interface DevkitOptions {
+    /**
+     * NativeWind 的 CSS 入口文件路径（相对于 projectRoot）。
+     * 默认：'./src/global.css'
+     */
+    input?: string;
+}
+/**
+ * 一站式应用所有 devkit Metro wrapper。
+ *
+ * @param config  Metro config 对象（来自 getDefaultConfig）
+ * @param options 配置选项
+ * @returns       完整配置后的 Metro config
+ */
+declare function withDevkit(config: MetroConfig, options?: DevkitOptions): MetroConfig;
+
+/**
+ * withDevStubs — Metro resolver 注入开发阶段 stub
+ *
+ * 注入行为：
+ *   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));
+ */
+
+/**
+ * 将开发阶段 stub 注入到 Metro config 中。
+ *
+ * @param config  Metro config 对象（来自 getDefaultConfig 或 getSentryExpoConfig）
+ * @returns       注入 resolveRequest 后的新 Metro config
+ */
+declare function withDevStubs(config: MetroConfig): MetroConfig;
+
 /**
- * 修复沙箱环境中 node_modules 位于项目父级目录时，资源文件（字体、图片等）加载返回 500 的问题。
+ * withWorkspaceNodeModules — 修复沙箱中 node_modules 不在 projectRoot 内时的模块解析问题
+ *
+ * 适用场景：node_modules 位于 projectRoot 的祖先目录（如 /workspace/node_modules），
+ * 而 projectRoot 自身的 node_modules 为空目录或不存在。
  *
- * 问题根因：
- *   pnpm 在沙箱中将 node_modules 安装到 projectRoot 的上层目录（如 /workspace/node_modules），
- *   而非 projectRoot 内（如 /workspace/app/node_modules）。
- *   Metro 处理 /assets/?unstable_path=./node_modules/.pnpm/... 请求时，会将路径解析为
- *   path.resolve(projectRoot, './node_modules/.pnpm/...')，得到一个不存在的路径，返回 500。
- *   实际文件在父级的 node_modules/.pnpm/ 下。
+ * 问题：Metro 只监听 projectRoot，不会自动爬取祖先目录的 node_modules，
+ *   导致 Metro 无法在 file map 中找到依赖的真实路径，bundle 请求返回 404。
  *
- * 修复方式：
- *   向上查找实际的 node_modules 目录，将其加入 watchFolders（让 Metro 索引其中的文件）
- *   和 resolver.nodeModulesPaths（让模块解析也能找到包）。
+ * 修复：将祖先目录中的 node_modules 加入 watchFolders 和 resolver.nodeModulesPaths，
+ *   使 Metro 能正确索引并解析其中的模块。
  *
- *   如果 node_modules 就在 projectRoot 下，则不做任何修改，直接返回原始 config。
+ * 用法（metro.config.js）：
+ *   const { withWorkspaceNodeModules } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withWorkspaceNodeModules(config);
+ */
+
+/**
+ * 修复沙箱环境中 node_modules 位于祖先目录时，Metro 模块解析和 bundle 请求失败的问题。
  *
  * @param config  Metro config 对象（来自 getDefaultConfig）
- * @returns       修正 watchFolders 和 nodeModulesPaths 后的新 Metro config
+ * @returns       修正 watchFolders、nodeModulesPaths 后的新 Metro config
  */
 declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
+
 /**
- * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
+ * withCssInterop — 为第三方 Expo 组件注入 NativeWind cssInterop
  *
  * 注入方式：Metro resolver 层拦截对应包的 import，重定向到 stub 文件。
  * stub 文件透传原包的所有导出，并调用 cssInterop 完成注册。
@@ -128,53 +225,17 @@ declare function withWorkspaceNodeModules(config: MetroConfig): MetroConfig;
  * 此函数在开发和生产环境均需启用（cssInterop 注册与环境无关）。
  * 支持与其他 Metro wrapper 链式组合。
  *
- * @param config  Metro config 对象
- * @returns       注入 resolveRequest 后的新 Metro config
- */
-declare function withCssInterop(config: MetroConfig): MetroConfig;
-/** patchNativeWindCachePath 的配置选项 */
-interface PatchNativeWindCacheOptions {
-    /**
-     * 缓存目录，相对于 process.cwd()（Metro 项目根目录），默认 .native-wind-cache。
-     * 与 package.json 同级，避免写入只读的 node_modules。
-     */
-    cacheDir?: string;
-}
-/**
- * 将 NativeWind 编译缓存从 node_modules/.cache 重定向到项目根目录下的自定义目录。
- *
- * ⚠️ 必须在 require('nativewind/metro') / require('react-native-css-interop/dist/metro')
- * 之前调用，否则 outputDirectory 已经固化，patch 无效。
- *
- * 原理：react-native-css-interop/dist/metro 在模块顶层用
- *   const outputDirectory = path.resolve(__dirname, "../../.cache")
- * 计算缓存路径。通过在 require 前临时替换 path.resolve，可将该值重定向到
- * 项目根目录下的自定义缓存目录，而无需 fork 或修改 node_modules 源码。
- *
- * 所有依赖 outputDirectory 的 NativeWind 行为（文件写入、虚拟模块 Map key、
- * Metro resolver 返回值、haste 事件）都会一致使用新路径，无需额外 Metro 层面的 patch。
- *
- * ⚠️ 已知限制：依赖 react-native-css-interop 使用 path.resolve 计算缓存路径，
- * 升级该依赖时需确认此假设仍然成立。
- *
  * 用法（metro.config.js）：
- *   const { patchNativeWindCachePath } = require('miaoda-expo-devkit/metro');
- *   patchNativeWindCachePath(); // 必须在 require nativewind/metro 之前调用
- *   const { withNativeWind } = require('nativewind/metro');
+ *   const { withCssInterop } = require('miaoda-expo-devkit/metro');
+ *   module.exports = withCssInterop(config);
  */
-declare function patchNativeWindCachePath(options?: PatchNativeWindCacheOptions): void;
+
 /**
- * withNativeWind 的 lazy wrapper。
- *
- * nativewind/metro 在模块顶层捕获 react-native-css-interop 的 withCssInterop 引用，
- * 因此必须在 patchNativeWindCachePath() 执行完之后才能加载 nativewind/metro。
- * 这里使用 lazy require（在函数调用时才加载），确保 nativewind 拿到已 patch 的
- * outputDirectory，而不需要在 metro.config.js 中手动处理加载顺序。
+ * 为第三方 Expo 组件注入 NativeWind cssInterop，使其支持 className prop。
  *
- * 用法（metro.config.js）：
- *   const { withNativeWind } = require('miaoda-expo-devkit/metro');
- *   // 不再需要 require('nativewind/metro')
+ * @param config  Metro config 对象
+ * @returns       注入 resolveRequest 后的新 Metro config
  */
-declare function withNativeWind(config: MetroConfig, options?: any): MetroConfig;
+declare function withCssInterop(config: MetroConfig): MetroConfig;
 
-export { type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withEntryInjection, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };
+export { type DevkitOptions, type InjectOptions, type PatchNativeWindCacheOptions, type RouteEndpointOptions, patchNativeWindCachePath, withCssInterop, withDevStubs, withDevkit, withEntryInjection, withNativeWind, withRouteEndpoint, withWorkspaceNodeModules };