Next.js使用自定义react-intl多语言包出现HTML不匹配警告及渲染问题

根因分析 #

你遇到的水合警告和文本不渲染问题由以下几个错误共同导致：

• 服务端与客户端返回结果不一致：useTranslation 中仅在服务端（window === undefined 场景）读取语言文件，客户端运行时LanguagesFile始终为undefined，t函数无返回值。导致服务端渲染返回了带Home文本的HTML，客户端hydration校验时对应位置无内容，触发不匹配警告，同时前端无法正常渲染文本。
• 服务端读取路径错误：直接使用相对路径./public/Languages.json读取文件，Next.js服务端运行时工作目录不固定，大概率找不到对应文件。
• 逻辑判断错误：原代码中判断语言配置缺失的条件错误使用了&&逻辑与，只有三个层级（语言文件/当前locale/对应key）同时不存在才会触发警告，实际应该用||逻辑或，任意一层缺失就应该提示。
• 无客户端加载逻辑：浏览器环境无法使用fs模块读取本地文件，原代码未实现客户端侧的语言文件加载逻辑。

修复方案 #

第一步：调整包内语言加载逻辑 #

将语言文件加载逻辑从useTranslation移到LanguageProvider，统一兼容服务端、客户端加载逻辑，保证两端数据一致：

// LanguageProvider.tsx
import { createContext, useContext, useEffect, useState, ReactNode } from 'react';

interface LanguageContextType {
  locale: string;
  setLang: (lang: string) => void;
  languages: Record<string, Record<string, string>>;
}

const LanguageContext = createContext<LanguageContextType>({} as LanguageContextType);

interface LanguageProviderProps {
  children: ReactNode;
  // 支持Next.js侧预加载的语言数据传入，优先使用
  initialLanguages?: Record<string, Record<string, string>>;
  initialLocale?: string;
}

export function LanguageProvider({ 
  children, 
  initialLanguages, 
  initialLocale = 'en-us' 
}: LanguageProviderProps) {
  const [locale, setLocale] = useState(initialLocale);
  const [languages, setLanguages] = useState<Record<string, Record<string, string>>>(initialLanguages || {});

  useEffect(() => {
    // 客户端如果没有传入预加载的语言数据，主动请求
    if (!initialLanguages) {
      fetch('/Languages.json')
        .then(res => res.json())
        .then(data => setLanguages(data))
        .catch(err => console.error('加载语言文件失败', err));
    }
  }, [initialLanguages]);

  const setLang = (lang: string) => setLocale(lang);

  return (
    <LanguageContext.Provider value={{ locale, setLang, languages }}>
      {children}
    </LanguageContext.Provider>
  );
}

export const useLanguageContext = () => useContext(LanguageContext);

第二步：重写useTranslation逻辑 #

// UseTranslation.tsx
import { useLanguageContext } from './LanguageProvider';

export function useTranslation() {
  const { locale, languages } = useLanguageContext();

  function t(key: string) {
    // 修正逻辑判断条件，用逻辑或
    if (!languages || !languages[locale] || !languages[locale][key]) {
      console.warn(`No string '${key}' for locale '${locale}'`);
      return '';
    }
    return languages[locale][key].toString() || '';
  }

  return t;
}

第三步：修复服务端读取路径（如果保留服务端fs读取逻辑） #

如果需要支持服务端直接读取，路径要改为基于项目根目录的绝对路径：

// 服务端读取代码
const fs = require('fs');
const path = require('path');
const LanguagesFile = fs.readFileSync(path.join(process.cwd(), 'public', 'Languages.json'), 'utf8');

第四步：Next.js项目侧适配（可选，彻底避免水合问题） #

让使用包的用户在页面的getServerSideProps中预加载语言文件，传入Provider，完全保证服务端客户端数据一致：

// pages/_app.js
import { LanguageProvider } from 'react-intl';
import fs from 'fs';
import path from 'path';

export default function MyApp({ Component, pageProps, languages }) {
  return (
    <LanguageProvider initialLanguages={languages}>
      <Component {...pageProps} />
    </LanguageProvider>
  )
}

export async function getServerSideProps() {
  const languagesFile = fs.readFileSync(path.join(process.cwd(), 'public', 'Languages.json'), 'utf8');
  const languages = JSON.parse(languagesFile);
  return {
    props: {
      languages
    }
  }
}

完成以上修改后，服务端和客户端拿到的语言数据完全一致，水合警告会消失，文本也可以正常渲染。

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