Metro打包工具中.mjs文件加载问题的深度解析

2025-06-07 12:39:48作者：薛曦旖Francesca

问题背景

在使用React Native生态中的Metro打包工具时，开发者可能会遇到一个特殊问题：当项目依赖的第三方库使用了ES模块格式(.mjs)时，Metro无法正确加载这些模块文件。这种情况在Expo项目中尤为常见，特别是当使用像@langchain/ollama这样的AI相关库时。

问题现象

具体表现为应用运行时控制台报错，提示找不到模块"ollama"，但实际上该模块确实存在于node_modules目录中。错误信息通常类似于"Unable to resolve module 'ollama/browser' from..."，这表明Metro在解析模块路径时出现了问题。

技术原理分析

现代JavaScript模块系统

现代JavaScript生态系统支持多种模块格式：

CommonJS(.cjs)：Node.js传统模块系统
ES模块(.mjs)：ECMAScript标准模块系统
混合模式：同时支持两种模块系统

package.json中的exports字段

Node.js 12+引入了package.json中的"exports"字段，它允许包作者：

为不同环境(require/import)指定不同的入口文件
创建子路径映射(如"ollama/browser"映射到"./dist/browser.mjs")
隐藏内部模块结构

Metro的模块解析机制

Metro作为React Native的打包工具，其模块解析机制与Node.js有所不同：

默认情况下，Metro 0.81需要显式启用exports字段支持
对.mjs文件的支持需要检查sourceExts配置
对子路径映射的处理需要特殊配置

解决方案

基础配置方案

对于大多数情况，修改metro.config.js文件即可解决问题：

const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

// 启用package.json exports字段支持
config.resolver.unstable_enablePackageExports = true;

module.exports = config;

高级配置方案

如果基础方案无效，可以尝试更全面的配置：

const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

// 确保包含所有必要的文件扩展名
config.resolver.sourceExts = [
  ...config.resolver.sourceExts,
  'mjs',
  'cjs'
];

// 启用所有高级解析功能
config.resolver.unstable_enablePackageExports = true;
config.resolver.unstable_conditionNames = ['import', 'require', 'default'];
config.resolver.unstable_conditionsByPlatform = {
  web: ['browser'],
  node: ['node']
};

module.exports = config;