Next.js + Zustand：Switched to client rendering because the server rendering errored 原因探索

荒唐镜 發表於 2025-6-18 11:38:00

Next.js + Zustand：Switched to client rendering because the server rendering errored 原因探索

<h1>🧩 前言</h1>
在使用 Zustand 进行状态管理时，我们很容易把注意力集中在组件本身，却忽略了状态模块背后的执行环境。当我在 Next.js App Router 中封装 <code data-start="288" data-end="302">useSortStore</code> 自定义 hook 时，遇到一个看似莫名其妙的错误：
<div class="cnblogs_code">
<pre>Error: Switched to client rendering because the server rendering errored:
Cannot read properties of null (reading 'useSyncExternalStore')</pre>
</div>
这段报错是我意识到“不是组件也要写 use client”的起点。
<h1 data-start="477" data-end="514">😵‍💫 问题1</h1>
<div class="cnblogs_code">
<pre>// store/useSortStore.ts
import { useStore } from 'zustand'
import { createStore } from 'zustand/vanilla'

const sortStore = createStore(() => ({
sortTag: 'latest',
setSort: (value) => set({ sortTag: value }),
}))

const useSortStore = (selector) => useStore(sortStore, selector)
export default useSortStore

// components/Sort.tsx
"use client"
import useSortStore from '@/store/useSortStore'

export function Sort() {
const sortTag = useSortStore(s => s.sortTag)
// ...
}</pre>
</div>
你以为没问题？但其实还是会在 SSR 阶段崩溃。
🧠 原因解析：模块顶层的“副作用”也会在 SSR 中运行
虽然组件是 <code data-start="1149" data-end="1163">"use client"</code> 的，但 <code data-start="1168" data-end="1185">useSortStore.ts</code> 模块没有 <code data-start="1193" data-end="1205">use client</code>，所以：
<ul data-start="1213" data-end="1346">
<li data-start="1213" data-end="1241">
它会被当作 Server Module 加载
</li>
<li data-start="1242" data-end="1298">
导致模块顶层执行 <code data-start="1253" data-end="1268">createStore()</code> 并导入 <code data-start="1273" data-end="1285">useStore()</code> 等 React Hook
</li>
<li data-start="1299" data-end="1346">
这些行为在 SSR 中触发 <code data-start="1315" data-end="1343">useSyncExternalStore(null)</code> 报错
</li>
</ul>
即使你从未在服务端主动调用这些代码，只要组件中 <code data-start="1374" data-end="1382">import</code> 了它，就会连带执行 SSR 预加载阶段的副作用。
<h2 data-start="1348" data-end="1409">✅ 结论：只要模块中用了 hook，不管是不是组件，都必须标记 <code data-start="1451" data-end="1465">"use client"</code></h2>
<hr>
 
<h1 data-start="477" data-end="514">😵‍💫问题升级：标记"use client", 依然尝试在server运行？</h1>
彻底解决：zustand中createStore需要懒加载。在客户端组件初始化的时候，再运行！
<div class="cnblogs_code">
<pre>let _store: StoreApi<SortStore> | null = null

function initSortStore() {
return createStore<SortStore>((set) => ({
 sortTag: 'latest',
 setSort: (tag) => set({ sortTag: tag }),
}))
}

function getStore(): StoreApi<SortStore> {
if (!_store) {
 _store = initSortStore()
}
return _store
}

function useSortStore<T>(selector: (state: SortStore) => T) {
const store = getStore()
return useStore(store, selector)
}

export default useSortStore</pre>
</div>
 
<h2 data-start="1348" data-end="1409">✅ 结论：zustand的全局store创建，需要lazy initialization</h2>
<hr>
 
<h1 data-start="477" data-end="514">😵‍💫 可能仍然有问题？</h1>
<h2 data-start="816" data-end="827">✅ 稳定写法建议</h2>
<ul data-start="829" data-end="950">
<li data-start="829" data-end="854">
✅ 必须放在文件最顶部（import 之前）；
</li>
<li data-start="855" data-end="887">
✅ 必须使用 双引号：<code data-start="872" data-end="886">"use client"</code>；
</li>
</ul>
<h1>😡 还是有问题，真相是？</h1>
推翻了以上所有结论，答案是使用create-next-app 的默认npm run dev 会使用Turbopack（热更新还有bug！！！），而非 webpack！！！
所以问题出在Turbopack！！！！！！！！！
解决：
1. 安装 npm install --save-dev cross-env
2. 修改package.json
<div class="cnblogs_code">
<pre>"scripts": {
"dev": "cross-env TURBOPACK=0 next dev"
}</pre>
</div>
不要用Turbopack!!!!!!!!!!! 
来源：https://www.cnblogs.com/sabertobih/p/18934485

頁: [1]

琼殿技术论坛's Archiver

Next.js + Zustand：Switched to client rendering because the server rendering errored 原因探索