Next.js中URL哈希变更仅在setTimeout下生效的原因及解决方法

问题描述 #

需要检测URL的哈希变化，尝试相关方案后均无效，仅通过setTimeout延迟1秒的方式能正常获取window.location.hash；同时使用hashchange事件结合useParams的写法也无法生效。

为什么setTimeout能生效？ #

Next.js的路由更新（包括哈希值变更）是异步过程。组件的useEffect默认在挂载完成后立即触发，此时浏览器的URL哈希可能还未完成更新。setTimeout延迟1秒后，路由更新的异步操作已完成，因此能拿到最新的哈希值。但这只是临时 workaround，延迟时间不可控，并非可靠的生产环境方案。

无效代码的问题分析 #

看你提供的这段代码：

const params = useParams();
const [url, setURL] = useState<string>('')
useEffect(() => {
    const update = () => {
        setURL(window.location.href.substring(window.location.href.indexOf('/', 9)))
    };
    window.addEventListener('hashchange', update);
    update(); // Initial fetch
    return () => window.removeEventListener('hashchange', update)
}, [params])
console.log(url)

存在几个核心问题：

1. useParams()不监听哈希变化：useParams用于获取动态路由参数（比如/posts/[id]中的id），和URL哈希完全无关。哈希变化不会触发params更新，因此依赖params的useEffect不会在哈希变更时重新执行。
2. 初始调用时机不对：组件挂载时调用update()，此时哈希可能还未完成更新，拿到的是旧值。
3. URL截取方式脆弱：window.location.href.substring(window.location.href.indexOf('/', 9))的写法依赖固定URL结构，一旦环境变化（比如域名长度不同）就会出错，且根本没直接获取哈希值。

正确的处理方式 #

方法1：正确监听hashchange事件 #

不需要依赖无关的params，直接在组件挂载时监听事件，同时确保初始值获取时机正确：

import { useState, useEffect } from 'react';

export default function YourComponent() {
  const [hash, setHash] = useState('');

  useEffect(() => {
    const updateHash = () => {
      setHash(window.location.hash);
    };

    // 初始获取哈希值
    updateHash();

    // 添加哈希变化监听
    window.addEventListener('hashchange', updateHash);

    // 组件卸载时清理监听
    return () => window.removeEventListener('hashchange', updateHash);
  }, []); // 空依赖，仅在组件挂载时执行一次

  console.log('当前哈希:', hash);
  return <div>当前哈希：{hash}</div>;
}

注意：如果是Next.js App Router，需要在组件顶部添加'use client'指令，因为window对象仅在浏览器端可用。

方法2：使用Next.js路由钩子（推荐） #

利用Next.js官方提供的路由钩子，能更精准地监听路由变化，包括哈希值：

App Router 写法

'use client';
import { useState, useEffect } from 'react';
import { useRouter } from 'next/navigation';

export default function YourComponent() {
  const router = useRouter();
  const [hash, setHash] = useState('');

  useEffect(() => {
    // 初始获取哈希
    setHash(window.location.hash);

    // 订阅路由变化，每次路由更新时同步哈希值
    const unsubscribe = router.subscribe(() => {
      setHash(window.location.hash);
    });

    // 组件卸载时取消订阅
    return unsubscribe;
  }, [router]);

  console.log('当前哈希:', hash);
  return <div>当前哈希：{hash}</div>;
}

Pages Router 写法

import { useState, useEffect } from 'react';
import { useRouter } from 'next/router';

export default function YourComponent() {
  const router = useRouter();
  const [hash, setHash] = useState('');

  useEffect(() => {
    const handleHashChange = () => {
      setHash(window.location.hash);
    };

    // 初始获取哈希
    handleHashChange();

    // 监听Next.js的哈希变化完成事件
    router.events.on('hashChangeComplete', handleHashChange);

    // 组件卸载时移除监听
    return () => {
      router.events.off('hashChangeComplete', handleHashChange);
    };
  }, [router]);

  console.log('当前哈希:', hash);
  return <div>当前哈希：{hash}</div>;
}

这种方式更贴合Next.js的路由机制，避免直接操作window带来的兼容性问题。

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