Next.js 13：使用useQueryParams时router.replace引发应用重挂载，求解决方案

问题分析 #

你的问题核心在于使用router.replace()拼接URL时的错误处理，以及路由更新方式的不规范，导致Next.js 13 App Router触发了不必要的组件重挂载。原代码中decodeURIComponent(newSearchParams.toString())是关键问题——URLSearchParams.toString()本身会生成符合标准的编码查询字符串，额外解码会破坏URL格式，触发路由的异常重处理。

解决方案1：规范路由更新逻辑（推荐） #

修正URL拼接方式，移除多余的解码操作，改用Next.js推荐的路由对象形式调用router.replace()，同时可选禁用滚动行为避免页面跳动：

'use client'; // 确保Hook在客户端组件环境中使用（或调用该Hook的组件添加此指令）

import { useRouter, useSearchParams, usePathname } from 'next/navigation';

export function useQueryParams() {
    const pathname = usePathname();
    const router = useRouter();
    const searchParams = useSearchParams()!;    

    const updateQueryParams = ({ query }: { query?: Record<string, string> }) => {
        const newSearchParams = new URLSearchParams(searchParams);
        Object.entries(query ?? {}).forEach(([key, value]) => {
            value !== '' ? newSearchParams.set(key, value) : newSearchParams.delete(key);
        });

        if (pathname) {
            // 使用路由对象形式调用replace，避免字符串拼接的格式问题
            router.replace({
                pathname,
                search: newSearchParams.toString(),
            }, {
                scroll: false, // 可选：保持当前滚动位置，不自动跳转到顶部
            });
        }
    };  

    return { update: updateQueryParams };
}

解决方案2：直接操作浏览器History API（谨慎使用） #

如果上述方法仍有问题，可以绕过Next.js路由系统直接修改浏览器历史记录，但需手动维护本地参数状态以同步useSearchParams：

'use client';

import { useSearchParams, usePathname } from 'next/navigation';
import { useState, useEffect } from 'react';

export function useQueryParams() {
    const pathname = usePathname();
    const searchParams = useSearchParams()!;
    // 本地维护查询参数状态，避免依赖路由触发重挂载
    const [localParams, setLocalParams] = useState(new URLSearchParams(searchParams));

    // 路由参数变化时同步本地状态
    useEffect(() => {
        setLocalParams(new URLSearchParams(searchParams));
    }, [searchParams]);

    const updateQueryParams = ({ query }: { query?: Record<string, string> }) => {
        const newParams = new URLSearchParams(localParams);
        Object.entries(query ?? {}).forEach(([key, value]) => {
            value !== '' ? newParams.set(key, value) : newParams.delete(key);
        });

        const searchStr = newParams.toString();
        const newUrl = `${pathname}${searchStr ? `?${searchStr}` : ''}`;
        
        // 直接修改浏览器历史，不触发Next.js路由重挂载
        window.history.replaceState({ ...window.history.state, as: newUrl, url: newUrl }, '', newUrl);
        
        // 更新本地状态
        setLocalParams(newParams);
    };

    return { update: updateQueryParams, params: localParams };
}

注意：此方法绕过了Next.js路由机制，可能导致路由缓存、服务器组件数据同步等特性失效，仅在必要场景使用。

额外注意事项 #

• 调用useQueryParams的组件必须是客户端组件（添加'use client'指令），因为useRouter、useSearchParams等Hook仅支持客户端环境。
• 避免在服务器组件中直接修改查询参数，所有交互逻辑应放在客户端组件中。

内容的提问来源于stack exchange，提问作者Shubham Chauhan