Expo 40+用TypeScript加载本地Markdown时assetsExt失效、模块解析失败求助

问题根因 #

Expo 40 版本迭代后，旧版本中通过 app.json 配置 assetsExt 标记可加载资源后缀的逻辑，已经不再被Metro打包服务识别为模块解析规则。

• 你之前添加的TypeScript类型声明仅能解决编译阶段的类型检查问题，让TS不会报导入md文件的类型错误
• 但运行时的模块解析完全由Metro打包服务负责，由于assetsExt配置失效，Metro没有将.md后缀纳入可解析的资源白名单，因此会抛出模块找不到的报错

具体修复步骤 #

1. 替换Metro打包配置（替代失效的assetsExt配置） #

打开项目根目录下的metro.config.js，在原有Expo默认配置的基础上，将md后缀加入Metro可解析的静态资源列表：

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

// 向Metro的可解析资源后缀列表中追加md格式
config.resolver.assetExts.push('md');

module.exports = config;

注意：可以将app.json中残留的assetsExt、packagerOpts.assetExts这类旧配置直接删除，避免旧规则干扰新的Metro配置。

2. 确认TypeScript类型声明生效 #

• 新建或修改项目根目录下types/markdown.d.ts文件，写入全局模块类型声明：

declare module '*.md' {
  const content: string;
  export default content;
}

• 打开tsconfig.json，确认include字段已经将types目录纳入编译范围，保证类型声明能被TS识别：

{
  "compilerOptions": {
    // 项目原有TS配置保持不变
  },
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "types/**/*.d.ts"
  ]
}

3. 验证导入逻辑 #

在组件中直接使用相对路径导入md文件即可，Metro会自动将md文件拷贝到打包资源目录，支持在运行时直接获取文件内容：

// 组件内导入示例
import guideContent from './assets/SOME_MARKDOWN.md';

// 导入得到的guideContent为文件的完整字符串内容，可直接传入Markdown渲染组件使用

常见踩坑排查 #

• 修改Metro配置后必须清空缓存重启开发服务，执行npx expo start -c，否则Metro会缓存旧的解析规则，依然报模块找不到的错误
• 确认导入的相对路径和实际文件位置完全匹配，React Native的路径解析对大小写敏感，路径大小写不一致也会触发文件不存在的报错
• 不要在导入路径中重复拼接文件后缀，避免出现路径匹配失败的问题

内容的提问来源于stack exchange，提问作者Jono