React Navigation嵌套路由报错：screens属性类型不存在问题

问题场景 #

在配置NavigationContainer的linking选项时，尝试嵌套路由出现TypeScript错误，原配置代码如下：

<NavigationContainer
    theme={navigation_theme}
    linking={{
        prefixes: ["https://startja.agenciaboz.com.br", "http://localhost:8081"],
        config: {
            screens: {
                home: {
                    path: "",
                    screens: {
                        login: "login",
                        budget: "budget",
                        budgetSuccess: "budget/success",
                        budgetFailed: "budget/failed",
                        forgotPassword: "forgot-password",
                        codeVerification: "forgot-password/verification",
                        resetPassword: "forgot-password/reset",
                        successComponent: "forgot-password/success",
                    },
                },
                notfound: "*",
            },
        },
    }}
    documentTitle={{ formatter: (options, route) => `Start Já - ${route?.name}` }}
>

错误信息 #

Object literal may only specify known properties, and 'screens' does not exist in type 'Omit<PathConfig<{}>, "screens" | "initialRouteName">'.ts(2353)
Providers.tsx(24, 25): The expected type comes from property 'home' which is declared here on type 'PathConfigMap<{ home: unknown; systemChooser: unknown; admin: unknown; resale: unknown; system: unknown; userSettings: unknown; customersSettings: unknown; resalesSettings: unknown; adminMasterSettings: unknown; notfound: unknown; }>'
⚠ Error (TS2353)  | 
Object literal may only specify known properties, and screens does not exist in type

问题原因 #

1. TypeScript类型推断缺失：home的类型被标记为unknown，无法识别其为嵌套导航器，因此不允许添加screens属性。
2. 配置结构冲突：给home设置path: ""后，对应的类型规则会排除screens属性，导致两者无法同时声明。

正确配置方式 #

方法1：定义路由类型（推荐） #

通过明确根路由和嵌套路由的参数类型，让TypeScript正确识别导航器结构：

// 定义Home导航器的子路由参数类型
type HomeStackParamList = {
  login: undefined;
  budget: undefined;
  budgetSuccess: undefined;
  budgetFailed: undefined;
  forgotPassword: undefined;
  codeVerification: undefined;
  resetPassword: undefined;
  successComponent: undefined;
};

// 定义根路由参数类型
type RootStackParamList = {
  home: undefined;
  notfound: undefined;
};

在导航器组件中绑定类型（以Stack导航器为例）：

import { createStackNavigator } from '@react-navigation/stack';

const HomeStack = createStackNavigator<HomeStackParamList>();
const RootStack = createStackNavigator<RootStackParamList>();

// 嵌套导航器结构
function HomeNavigator() {
  return (
    <HomeStack.Navigator>
      <HomeStack.Screen name="login" component={LoginScreen} />
      {/* 其他子屏幕组件 */}
    </HomeStack.Navigator>
  );
}

// 根导航器
function RootNavigator() {
  return (
    <RootStack.Navigator>
      <RootStack.Screen name="home" component={HomeNavigator} />
      <RootStack.Screen name="notfound" component={NotFoundScreen} />
    </RootStack.Navigator>
  );
}

此时保留原linking配置即可，TypeScript会正确识别screens属性：

<NavigationContainer
    theme={navigation_theme}
    linking={{
        prefixes: ["https://startja.agenciaboz.com.br", "http://localhost:8081"],
        config: {
            screens: {
                home: {
                    path: "",
                    screens: {
                        login: "login",
                        budget: "budget",
                        budgetSuccess: "budget/success",
                        budgetFailed: "budget/failed",
                        forgotPassword: "forgot-password",
                        codeVerification: "forgot-password/verification",
                        resetPassword: "forgot-password/reset",
                        successComponent: "forgot-password/success",
                    },
                },
                notfound: "*",
            },
        },
    }}
    documentTitle={{ formatter: (options, route) => `Start Já - ${route?.name}` }}
>
  <RootNavigator />
</NavigationContainer>

方法2：调整linking配置结构 #

如果不想定义类型，可移除home的path: ""，将空路径分配给home的初始子路由，实现相同的路径匹配效果：

<NavigationContainer
    theme={navigation_theme}
    linking={{
        prefixes: ["https://startja.agenciaboz.com.br", "http://localhost:8081"],
        config: {
            screens: {
                home: {
                    screens: {
                        login: "", // 空路径对应根路由，匹配home/login
                        budget: "budget",
                        budgetSuccess: "budget/success",
                        budgetFailed: "budget/failed",
                        forgotPassword: "forgot-password",
                        codeVerification: "forgot-password/verification",
                        resetPassword: "forgot-password/reset",
                        successComponent: "forgot-password/success",
                    },
                },
                notfound: "*",
            },
        },
    }}
    documentTitle={{ formatter: (options, route) => `Start Já - ${route?.name}` }}
>

此配置下，https://startja.agenciaboz.com.br/会匹配home/login，https://startja.agenciaboz.com.br/budget匹配home/budget，既满足嵌套路由需求，也能规避TypeScript错误。

内容的提问来源于stack exchange，提问作者Alfredo Augusto Petri