Next.js中含react-idle-timer组件调用i18n.changeLanguage触发页面二次重载

问题背景 #

在Next.js应用中，登录后主UI路由由<MainApp>组件渲染，该组件内嵌基于react-idle-timer实现的<SessionTimer>用于会话超时跟踪。当用户在该架构内点击语言切换链接调用i18n.changeLanguage()时，会出现异常的页面二次重载：

1. 首次触发时正常完成内联翻译（无刷新）
2. 约1秒后页面自动重载

移除<SessionTimer>或在非<MainApp>架构页面中操作时，语言切换仅保留正常内联翻译，无重载问题。已确认react-idle-timer的onIdle/onAction/onPrompt回调未被触发，推测是语言切换引发的组件重渲染触发了react-idle-timer的幕后行为，进而导致页面重载。

解决方案 #

方案1：稳定useIdleTimer的依赖与回调函数 #

语言切换会触发组件树重渲染，若useIdleTimer的回调函数每次渲染都重新创建，可能导致定时器内部逻辑异常。通过useRef和useEffect稳定回调，避免不必要的定时器重新初始化：

import { useIdleTimer, IIdleTimer } from "react-idle-timer";
import { useRef, useEffect } from "react";

export const SessionTimer = () => {
    // 用ref保存回调，避免每次渲染生成新函数
    const handleOnIdle = useRef(async (event: any) => {
        // 你的原有onIdle逻辑
    });
    const handleOnAction = useRef(async () => {
        // 你的原有onAction逻辑
    });
    const handleOnPrompt = useRef((event: any) => {
        // 你的原有onPrompt逻辑
    });

    const idleTimer: IIdleTimer = useIdleTimer({
        timeout: 1000 * 60 * 20, // 20分钟
        onIdle: handleOnIdle.current,
        onPrompt: handleOnPrompt.current,
        onAction: handleOnAction.current,
        debounce: 500,
        // 仅监听用户主动交互事件，减少DOM变化误触发
        events: ['mousemove', 'keydown', 'mousedown', 'touchstart']
    });

    // 仅在必要时更新回调（若回调依赖外部状态，可添加到依赖数组）
    useEffect(() => {
        handleOnIdle.current = async (event: any) => { /* 你的逻辑 */ };
        handleOnAction.current = async () => { /* 你的逻辑 */ };
        handleOnPrompt.current = (event: any) => { /* 你的逻辑 */ };
    }, []);

    return null;
};

方案2：语言切换前后暂停/恢复IdleTimer #

语言切换会导致大量DOM重渲染，可能被react-idle-timer的检测逻辑误判。通过控制定时器的暂停与恢复，避免重渲染期间触发异常行为：

步骤1：改造<SessionTimer>暴露控制方法

import { useIdleTimer, IIdleTimer } from "react-idle-timer";
import { useRef, useImperativeHandle, forwardRef } from "react";

export const SessionTimer = forwardRef((_, ref) => {
    const idleTimerRef = useRef<IIdleTimer | null>(null);

    useIdleTimer({
        timeout: 1000 * 60 * 20,
        onIdle: handleOnIdle,
        onPrompt: handleOnPrompt,
        onAction: handleOnAction,
        debounce: 500,
        onInit: (timer) => {
            idleTimerRef.current = timer;
        }
    });

    // 向父组件暴露暂停/恢复方法
    useImperativeHandle(ref, () => ({
        pause: () => idleTimerRef.current?.pause(),
        resume: () => idleTimerRef.current?.resume()
    }));

    const handleOnIdle = async (event: any) => { /* 你的逻辑 */ };
    const handleOnAction = async () => { /* 你的逻辑 */ };
    const handleOnPrompt = (event: any) => { /* 你的逻辑 */ };

    return null;
});

SessionTimer.displayName = "SessionTimer";

步骤2：在语言切换组件中控制定时器

import { useTranslation } from "react-i18next";
import { useRef } from "react";
import { SessionTimer } from "./SessionTimer";

const LanguageSwitcher = () => {
    const { t, i18n } = useTranslation(['shared']);
    const sessionTimerRef = useRef<{ pause: () => void; resume: () => void }>(null);

    const changeLanguage = async (e: any) => {
        e.preventDefault();
        const language = t('switchLanguage', { ns: ['shared'] });

        // 切换前暂停定时器
        sessionTimerRef.current?.pause();

        // 设置NEXT_LOCALE cookie
        const days = 30;
        const date = new Date();
        date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000);
        const expires = date.toUTCString();
        document.cookie = `NEXT_LOCALE=${language};expires=${expires};path=/`;

        // 完成语言切换
        await i18n.changeLanguage(language);

        // 延迟恢复定时器，确保DOM渲染完成
        setTimeout(() => {
            sessionTimerRef.current?.resume();
        }, 500);
    };

    return (
        <>
            <a onClick={changeLanguage}>切换语言</a>
            {/* 若SessionTimer在<MainApp>中，需通过props传递ref */}
            <SessionTimer ref={sessionTimerRef} />
        </>
    );
};

方案3：调整next-i18n-router配置 #

设置NEXT_LOCALE cookie后，next-i18n-router可能因自动检测locale变化触发页面重载。可关闭自动重定向：

// i18n-router.config.js
export default {
    locales: ['en', 'zh'], // 你的语言列表
    defaultLocale: 'en',
    disableAutoRedirect: true // 禁用自动重定向，避免cookie变化触发重载
};

内容的提问来源于stack exchange，提问作者gene b.