将 Expo Router 从 SDK 55 迁移到 SDK 56

学习如何使用代码转换工具或手动将 Expo Router 从 SDK 55 迁移到 56。

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

在 SDK 56 及更高版本 中，Expo Router 不再支持在应用代码中从外部 @react-navigation/* 包导入。请将这些导入更新为匹配的 expo-router 入口点。运行时 API 没有变化——只是模块指定符发生了移动。

🌐 In SDK 56 and later, Expo Router no longer supports importing from external @react-navigation/* packages in application code. Update those imports to the matching expo-router entry points. The runtime API is unchanged - only the module specifiers move.

自动迁移

🌐 Automated migration

从项目根目录运行 codemod。它会将应用代码中的 @react-navigation/* 导入重写为匹配的 expo-router 入口点。

🌐 Run the codemod from the root of your project. It rewrites @react-navigation/* imports in your application code to the matching expo-router entry points.

将 src 替换为包含你的应用代码的目录或通配符。

🌐 Replace src with the directory or glob that contains your application code.

手动迁移

🌐 Manual migration

如果你无法运行 codemod，请手动重新指向每个导入：

🌐 If you cannot run the codemod, repoint each import by hand:

// Before (SDK 55)
import { ThemeProvider, DarkTheme } from '@react-navigation/native';
import { createMaterialTopTabNavigator } from '@react-navigation/material-top-tabs';

// After (SDK 56)
import { ThemeProvider, DarkTheme } from 'expo-router/react-navigation';
import { createMaterialTopTabNavigator } from 'expo-router/js-top-tabs';

使用下表将代码中的每个 React Navigation 导入映射到其 expo-router 等效项：

🌐 Use the following table to map each React Navigation import in your code to its expo-router equivalent:

库

🌐 Libraries

许多第三方库仍然从 @react-navigation/core 导入。为了简化 SDK 56 的迁移，当这些导入来自 node_modules 时，Expo CLI 会自动将它们重写为 expo-router。你的应用代码不会受到此重写的影响。

🌐 Many third-party libraries still import from @react-navigation/core. To ease the SDK 56 transition, Expo CLI automatically rewrites those imports to expo-router when they originate from node_modules. Your application code is unaffected by this rewrite.

这是一个临时的兼容性补丁。专门的库迁移指南将在自动重写被移除之前说明替代方案。

🌐 This is a temporary compatibility shim. A dedicated library migration guide will explain the replacement before the automatic rewrite is removed.

要选择退出，请在启动打包器之前在环境中设置 EXPO_ROUTER_DISABLE_RN_NAVIGATION_CHECK=1。这也会禁用应用代码从 @react-navigation/* 导入时的打包器错误。

🌐 To opt out, set EXPO_ROUTER_DISABLE_RN_NAVIGATION_CHECK=1 in your environment before starting the bundler. This also disables the bundler error for application code that imports from @react-navigation/*.