创建新Expo应用后运行expo start遭遇Metro解析错误

问题场景 #

• 执行npx create-expo-app <MyApp>创建全新项目，未做任何代码修改
• 运行npx expo start直接触发Metro解析错误
• 已尝试删除node_modules、package.json后重新npm install，问题依旧

报错信息 #

终端报错 #

Call Stack
  <unknown> (.)

Metro error: Unable to resolve module .\node_modules\expo-router\entry from C:\Users\parys\OneDrive\Documents\GitHub\Test\test2/.: .\node_modules\expo-router\entry could not be found within the project or in these directories:
  node_modules
  ..\..\..\..\..\node_modules

本地主机报错 #

Static Rendering Error (Node.js)
Unable to resolve module .\node_modules\expo-router\entry from C:\Users\parys\OneDrive\Documents\GitHub\Test\test2/.: .\node_modules\expo-router\entry could not be found within the project or in these directories:
  node_modules
  ..\..\..\..\..\node_modules

解决方案 #

• 检查并安装expo-router依赖
  全新Expo项目默认不会自动包含expo-router（除非创建时指定路由模板），查看package.json如果没有该依赖，执行安装：

  npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar
  

• 清理Metro缓存
  缓存异常可能导致路径解析错误，启动时强制清理缓存：

  npx expo start --clear
  

• 修正Windows路径解析配置
  报错中的路径分隔符问题可能导致Metro无法正确定位模块，在项目根目录创建metro.config.js，添加以下配置：

  const path = require('path');
  const { getDefaultConfig } = require('@expo/metro-config');
  
  const config = getDefaultConfig(__dirname);
  
  config.resolver.nodeModulesPaths = [
    path.resolve(__dirname, 'node_modules'),
    path.resolve(__dirname, '../node_modules'),
  ];
  
  module.exports = config;
  

• 修正重装依赖的正确操作
  不要删除package.json（这是项目依赖的核心配置文件），正确的重装步骤是：

  # Windows系统
  rmdir /s /q node_modules
  del package-lock.json
  npm install
  
  # macOS/Linux系统
  rm -rf node_modules package-lock.json
  npm install
  

• 更新Expo CLI版本
  旧版本CLI可能存在兼容性问题，更新到最新版：

  npm install -g expo-cli
  

  或者直接调用最新版启动：

  npx expo@latest start
  

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