多层npm依赖下react-intl useIntl在深层UI包报无IntlProvider错误

问题背景 #

项目存在三层依赖链路：

• App 项目：根节点已配置 IntlProvider
• AppComponents 包：App 项目的直接依赖，包内调用 useIntl 功能正常
• UI 包：AppComponents 的依赖，包内调用 useIntl 抛出异常

具体报错信息：

Uncaught Error: [React Intl] Could not find required intl object. needs to exist in the component ancestry.

当前使用的技术栈版本：

• react-intl v6.0.4
• react v18.0.0
• node v18.0.0
• npm v8.6.0

相关代码片段 #

App 项目自定义 I18nProvider 实现：

import { useMemo, useState, createContext } from 'react';
import { IntlProvider } from 'react-intl';
import { ReactNode } from 'react';
import { MessageFormatElement } from 'react-intl';

export type TTranslationData = Record<string, string> | Record<string, MessageFormatElement[]>;

export interface II18nContext {
    locale: string;
    setLocale: (newLocale: string) => void;
    setTranslation: (data: TTranslationData) => void;
}

export interface II18nProviderProps {
    children: ReactNode;
}

const I18nContext = createContext<II18nContext | null>(null);

function I18nProvider({ children }: II18nProviderProps) {
    const [locale, setLocale] = useState(navigator.language);
    const [message, setMessage] = useState<TTranslationData | Record<string, never>>({});

    const value = useMemo(
        () => ({
            locale,
            setLocale,
            setTranslation: (data: TTranslationData) => setMessage(data),
        }),
        [locale],
    );

    return (
        <I18nContext.Provider value={value}>
            <IntlProvider locale={locale} messages={message}>
                <App />
            </IntlProvider>
        </I18nContext.Provider>
    );
}

UI 包内报错的 Searchbar 组件：

import { useIntl } from 'react-intl';

function Searchbar(props: SearchbarProps) {
    const intl = useIntl();

    return (
        {intl.formatMessage({
            id: 'searchbar.placeholder',
            description: 'React UI search bar placeholder',
            defaultMessage: 'Search',
        })}
    );
}

根因分析 #

该问题本质是依赖多实例导致Context不互通：
React Context 的匹配规则严格依赖包引用的唯一性。npm 安装多层依赖时，如果没有做版本强制统一，AppComponents、UI 包可能会在自身的 node_modules 目录下安装独立的 react、react-intl 副本。
这种情况下，UI 包内调用的 useIntl 读取的是自身目录下 react-intl 实例创建的 Context，而 App 项目中使用的 IntlProvider 来自根目录下的 react-intl 实例，两个实例创建的 Context 完全独立，自然无法读取到注入的 intl 对象。
AppComponents 能正常运行，是因为它的依赖被 npm 提升到了根 node_modules 目录，和 App 项目使用的是同一个 react-intl 实例，不存在Context不匹配的问题。

修复方案 #

1. 强制全项目依赖单实例
   在 App 项目的 package.json 中添加 overrides 配置，强制所有层级依赖使用根项目声明的 react、react-dom、react-intl 版本，从安装层面杜绝多副本问题：

   {
     "overrides": {
       "react": "$react",
       "react-dom": "$react-dom",
       "react-intl": "$react-intl"
     }
   }
   

   配置完成后删除 node_modules 目录和 package-lock.json 锁文件，重新执行 npm install 安装依赖。
   如果是 monorepo 架构，可以直接把 react、react-intl 声明为所有子包的 peerDependencies，子包不单独安装这两个包的实体版本，统一从根项目引用。
2. 校验依赖唯一性
   依赖安装完成后，执行 npm ls react 和 npm ls react-intl 检查依赖树，确认输出中不存在重复安装在子包 node_modules 下的 react、react-intl 副本即可。
3. 修正Provider渲染逻辑
   现有 I18nProvider 代码中 IntlProvider 内部直接硬编码渲染 <App />，没有使用传入的 children 属性，会导致挂载在 I18nProvider 下的其他子组件无法拿到上下文，建议修正为：

   return (
       <I18nContext.Provider value={value}>
           <IntlProvider locale={locale} messages={message}>
               {children}
           </IntlProvider>
       </I18nContext.Provider>
   );
   

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