企业官网建设流程全解析

1. “caveman”不是远古人，是React开发圈里一个正在冒头的轻量级状态管理工具

最近在几个前端技术群和GitHub Trending页上反复看到caveman这个词，和token、useMemo、npx、React紧密捆绑出现。它既不是AI模型名，也不是某个新出的加密货币代币，更不是某款复古游戏——而是一个极简、零依赖、专为现代React（v18+）设计的状态管理库。我第一次见到它是在一个React画布（Canvas）项目里，开发者用三行代码替换了原本要写80行的 Zustand + React-Query 组合逻辑，当时我就意识到：这东西有点意思。

它的核心定位非常清晰：不接管全局状态，不引入中间件，不抽象Store概念，只做一件事——让useMemo的缓存能力真正“可预测、可复用、可调试”。你可能马上会问：useMemo不是React自带的吗？为什么还要封装？答案藏在真实开发场景里：当组件层级变深、依赖项变复杂、re-render频率升高时，useMemo的缓存行为会变得“不可控”——它受React内部调度影响，可能被提前丢弃；它无法跨组件共享缓存结果；它没有生命周期钩子，没法做清理或预加载。而caveman正是为解决这三个痛点而生。

它和当前主流方案有本质区别：Zustand面向“状态持有”，Jotai面向“原子粒度”，Redux面向“可追溯性”，而caveman面向“计算复用性”。它不存state，只存memoized value + 依赖快照 + 失效策略。你可以把它理解成一个带版本控制的useMemo增强器，或者一个轻量级的“函数式缓存代理”。它不强制你改写组件结构，不新增Provider，不侵入JSX，只需要把原本写在组件内的useMemo逻辑，换成caveman.useMemo，就能获得确定性缓存、跨组件复用、手动失效等能力。

适合谁用？不是所有项目都需要它。如果你正面临这些情况，它很可能就是那个“少写50行代码、少调3次接口、少修2个缓存bug”的关键工具：

• 做数据可视化/画布类应用（比如flowork那种React画布），频繁计算节点布局、路径坐标、缩放矩阵；
• 构建AI智能体前端（如基于React模式构建能思考与行动的AI智能体），需要缓存prompt token生成结果、历史对话摘要、工具调用响应；
• 开发登录态强相关的系统（大量出现token exchange failed、token endpoint returned 403等错误），需稳定缓存access_token解析结果、权限树、用户profile，避免因token刷新失败导致UI反复闪退；
• 团队在推行“通用React开发标准”，但发现不同人对useMemo的理解和用法差异巨大，急需一个统一、可测试、可审计的缓存规范。

它不是银弹，但它是当前React生态里，少有的、把“函数式缓存”这件事做到极致的工具。接下来我会从设计思路、核心机制、实操细节到避坑经验，一层层拆开给你看——不是讲API文档，而是还原一个资深前端在真实项目中如何评估、接入、调优并最终离不开它的全过程。

2. 为什么是caveman？——从useMemo的三大缺陷说起

要真正理解caveman的价值，必须先直面useMemo在生产环境中的三个“沉默杀手级缺陷”。这不是理论问题，而是我在过去三年维护6个中大型React项目时，反复踩坑、反复重构后总结出的真实痛点。它们不会报错，但会让性能优化变成玄学，让Bug排查变成猜谜。

2.1 缓存不可控：React可能随时丢弃你的memoized值

官方文档里那句“useMemo只是性能优化，不是语义保证”听起来很温和，但在高交互场景下就是定时炸弹。举个典型例子：你在flowork这类React画布中，用useMemo计算一个节点的绝对坐标：

const absolutePosition = useMemo(() => { return calculateAbsolutePosition(node, parentTransform); }, [node.x, node.y, node.rotation, parentTransform]);

看起来没问题。但当画布滚动、缩放、同时拖拽多个节点时，React的并发渲染机制（Concurrent Rendering）可能在内存压力下主动丢弃这个缓存。结果就是：同一帧内，absolutePosition可能被重新计算2~3次，而你完全无法感知——因为useMemo不提供任何缓存命中率监控、不暴露缓存状态、不支持手动保留。我曾在一个金融图表项目里，因为这个原因导致CPU占用飙升30%，最后靠加console.log硬查才发现是useMemo被反复丢弃。

caveman的解法很直接：它把缓存从React的内部调度中剥离出来，自己管理缓存生命周期。它使用WeakMap存储value + deps快照，并通过一个轻量级引用计数器（ref counter）判断是否可回收。只要还有组件在使用该缓存，它就不会被GC；即使组件卸载，你也可以选择保留（用于后续快速恢复）。这不是魔法，而是把“缓存是否有效”这个黑箱，变成了一个可读、可写、可观察的明确状态。

2.2 缓存不可复用：每个组件都是孤岛

这是团队协作中最让人头疼的问题。假设你有两个组件：UserProfileCard和UserPermissionPanel，都需要解析同一个JWT token获取用户角色：

// UserProfileCard.tsx const userRole = useMemo(() => { return parseToken(token).role; }, [token]); // UserPermissionPanel.tsx const userRole = useMemo(() => { return parseToken(token).role; }, [token]);

表面上看，逻辑一致，依赖相同。但React会为每个组件创建独立的useMemo实例，意味着parseToken被调用了两次，且两次结果无法共享。如果parseToken涉及base64解码+JSON.parse+字段校验（实际JWT解析远比这重），这就是纯属浪费。

caveman通过“缓存键命名空间”解决这个问题。你可以为同一计算逻辑定义全局唯一key：

// sharedCache.ts export const userRoleCache = caveman.useMemo( () => parseToken(token).role, [token], { key: 'user-role-parser' } // 全局唯一标识 ); // UserProfileCard.tsx const userRole = userRoleCache(); // UserPermissionPanel.tsx const userRole = userRoleCache();

注意：这里userRoleCache是一个函数调用，不是React Hook调用。它内部会检查key是否存在，存在则复用已有缓存，不存在才执行计算。这意味着：

• 同一key下，所有调用共享同一份缓存结果；
• 缓存失效时，所有调用者同步更新；
• 你可以像导入普通函数一样，在任意文件中使用，无需Context或Provider；
• 它天然支持SSR——服务端预计算一次，客户端直接复用。

这背后其实是caveman对React Hooks规则的巧妙绕过：它不违反“Hook只能在组件顶层调用”的限制，因为它本身不是Hook，而是一个返回Hook调用结果的工厂函数。这种设计让它既能享受React的响应式能力，又摆脱了组件作用域的束缚。

2.3 缓存不可调试：没有缓存日志，就没有真相

当你遇到token exchange failed: error sending request这类错误时，第一反应往往是检查网络、检查token有效期、检查后端endpoint。但很少有人想到：可能是缓存了过期的token解析结果，导致后续请求带着无效payload发出去。而useMemo对此完全无能为力——你无法知道它当前缓存的是什么值，无法知道它上次计算是什么时候，无法知道它因何失效。

caveman内置了可选的调试模式（dev-only），启用后会在控制台输出结构化缓存日志：

[caveman] CACHE HIT: 'user-role-parser' (deps: ["eyJhbGciOi..."]) [caveman] CACHE MISS: 'api-response-cache' (deps: ["/v1/users", "GET"]) [caveman] CACHE INVALIDATED: 'user-role-parser' (reason: deps changed)

更重要的是，它提供了caveman.inspect(key)API，让你在DevTools控制台实时查看缓存状态：

// 在浏览器控制台输入 caveman.inspect('user-role-parser') // 返回： { value: 'admin', deps: ['eyJhbGciOi...'], lastUpdated: 1718234567890, hitCount: 12, missCount: 3 }

这个能力在排查sign-in could not be completed token exchange failed类问题时极其关键。我们曾在一个SaaS后台项目中，发现登录后部分页面权限异常。通过caveman.inspect('user-permissions')发现缓存值还是旧token解析结果，而新token已刷新——根源是token刷新逻辑没触发缓存失效。有了这个工具，3分钟定位，5分钟修复，而不是花半天翻日志、加断点、模拟各种登录路径。

这三点缺陷，单独看都不致命，但叠加起来，就是React应用中“性能优化反噬”的经典范式。caveman不做大而全的状态管理，它只专注解决这一个切口：让函数式缓存变得可控、可复用、可调试。它的哲学是：“不要试图管理状态，去管理计算”。

3. 核心机制深度拆解：caveman如何实现确定性缓存

caveman的源码不到300行（不含TypeScript类型定义），但它用极简的代码实现了三个关键机制：依赖快照比对、缓存键标准化、失效策略可配置。理解这三点，你就掌握了它的全部灵魂，也能判断它是否适合你的项目。

3.1 依赖快照比对：不是浅比较，而是深度冻结快照

useMemo的依赖数组比对是浅比较（shallow equality），即[a, b] === [a, b]永远为false。这导致两个常见陷阱：

• 对象/数组依赖总被视为“变化”，缓存永远不命中；
• 函数依赖（如event handler）每次渲染都新建，导致缓存失效。

caveman的解法是：对依赖数组执行深度冻结快照（deep freeze snapshot），然后进行引用比对。它不使用lodash.isEqual这类重量级深比较，而是用一个精巧的递归冻结算法：

function freezeDeps(deps: any[]): readonly any[] { return deps.map(dep => { if (dep === null || typeof dep !== 'object') return dep; if (Array.isArray(dep)) { return Object.freeze(dep.map(item => freezeDeps([item])[0])); } if (typeof dep === 'function') { // 函数不冻结，但提取其toString()签名作为指纹 return Object.freeze({ __fn__: dep.toString().slice(0, 100) }); } // 普通对象，递归冻结所有自有属性 const frozen = {} as any; Object.keys(dep).forEach(key => { frozen[key] = freezeDeps([dep[key]])[0]; }); return Object.freeze(frozen); }); }

这个算法的关键在于：

• 对数组，冻结其元素（递归）；
• 对函数，不冻结本体（避免闭包污染），而是取toString()前100字符作为唯一指纹——实践中，同一函数的toString几乎不变，且足够区分不同函数；
• 对普通对象，冻结所有自有属性（不处理原型链，避免无限递归）；
• 最终返回一个完全冻结的只读结构，确保===比对可靠。

实测效果：在我们的AI智能体项目中，一个包含5个嵌套对象、3个箭头函数的依赖数组，useMemo命中率不足20%，而caveman达到98%。因为那些“看似变化”的函数和对象，在冻结快照后，引用完全一致。

提示：这个机制默认启用，但如果你确定依赖全是原始值（string/number/boolean），可以通过{ shallow: true }选项关闭冻结，提升微小性能（约0.1ms）。

3.2 缓存键标准化：从字符串到可序列化的唯一ID

caveman的key选项不是简单字符串，而是一个可序列化的唯一标识生成器。它支持三种形式：

它的序列化逻辑非常务实：

• 字符串直接使用；
• 函数调用后转字符串；
• 对象按JSON.stringify规则序列化，但会过滤掉函数、undefined、Symbol等不可序列化值，避免JSON.stringify报错；
• 所有key最终都会经过String(key).replace(/[^a-zA-Z0-9_-]/g, '_')清洗，确保安全可用。

这个设计解决了实际开发中的关键问题：

• 避免key冲突：'user-123'和'user-456'天然隔离；
• 支持批量操作：caveman.clearKeys(/^user-.*/)一键清空所有用户相关缓存；
• 便于监控：所有key自动上报到内部统计模块，可导出缓存热力图。

我们在一个GitLab集成项目中，用对象key管理不同仓库的API token缓存：

const repoTokenCache = caveman.useMemo( () => fetchRepoToken(repoId), [repoId], { key: { namespace: 'gitlab-token', repoId } } );

这样，当用户切换仓库时，旧缓存自动失效，新缓存独立创建，且可通过caveman.inspect({ namespace: 'gitlab-token', repoId: 'abc' })精准调试，彻底告别login failed. check api token or gitlab version.这类模糊错误。

3.3 失效策略可配置：不只是“依赖变就失效”

useMemo的失效逻辑单一：依赖数组任一元素变化，缓存立即丢弃。但真实业务中，失效往往需要更精细的控制。caveman提供了四种策略：

最实用的是manual模式。比如处理your access token could not be refreshed错误时：

// authService.ts export const refreshToken = async () => { try { const newToken = await api.refresh(); // 刷新成功，手动失效所有token相关缓存 userRoleCache.invalidate(); userPermissionsCache.invalidate(); apiClientCache.invalidate(); } catch (e) { // 刷新失败，清除缓存避免后续请求用旧token caveman.clearKeys(/^auth-.*/); } };

这里invalidate()不是简单删除，而是标记缓存为“待失效”，下次调用时才会重新计算。这样能避免在刷新过程中，多个组件同时触发重复计算。我们实测，在高并发登录场景下，manual模式将token相关API调用减少73%。

注意：onEvent策略依赖window.dispatchEvent，所以它天然支持跨iframe通信。我们在一个嵌入式仪表盘项目中，主应用登出时触发new CustomEvent('auth:logout')，所有嵌入的React微前端立即同步失效缓存，完美解决sign-in failed: login server error: token exchange failed的跨域状态不一致问题。

4. 实操全流程：从零开始接入caveman，解决真实业务问题

现在我们来走一遍完整实操流程。我会以一个典型的“React画布+AI智能体”项目为背景，演示如何用caveman解决token用量监控、prompt token预估、flowork画布布局计算三大痛点。所有代码均可直接复制运行，参数和配置均来自我们线上项目的实测值。

4.1 环境准备与安装：npx一键初始化

caveman的安装极其轻量，零依赖，无构建步骤。它甚至不需要Webpack或Vite——因为它的核心就是一个ESM模块，浏览器原生支持。

# 方式1：npm安装（推荐，便于TypeScript类型推导） npm install caveman # 方式2：npx直接运行（适合快速验证） npx caveman init # 这会创建一个最小demo项目，含React 18 + TypeScript + caveman示例

npx caveman init命令做了三件事：

• 创建src/caveman.config.ts，预设常用配置；
• 在src/main.tsx中注入全局调试开关；
• 生成src/examples/useTokenUsage.ts示例文件。

配置文件内容如下（已根据我们项目调优）：

// src/caveman.config.ts import { CavemanConfig } from 'caveman'; export const cavemanConfig: CavemanConfig = { // 开发环境启用详细日志 debug: import.meta.env.DEV, // 生产环境自动禁用日志，零性能损耗 production: import.meta.env.PROD, // 缓存最大容量，超过后按LRU策略淘汰 maxCacheSize: 1000, // 默认TTL，单位毫秒（0表示永不过期） defaultTtl: 0, // 错误处理：捕获计算函数异常，返回undefined而非崩溃 onError: (error, key) => { console.warn(`[caveman] Cache computation failed for ${key}:`, error); } };

实操心得：maxCacheSize不要设得过大。我们最初设为5000，结果在低端Android设备上引发内存警告。实测1000是平衡点——既能覆盖绝大多数缓存需求，又不会占用过多内存。你可以用caveman.stats()实时监控当前缓存数量。

4.2 解决token用量监控问题：精确计算prompt token消耗

AI应用开发中，prompt token用量直接影响成本和速率限制。但OpenAI等API返回的usage字段只在响应体中，前端无法提前预估。传统做法是硬编码估算，误差常达±30%。caveman让我们能构建一个可复用、可验证、可调试的token用量计算器。

// src/lib/tokenUsage.ts import { caveman } from 'caveman'; import { estimateTokens } from 'gpt-tokenizer'; // 轻量级tokenizer库 // 关键：使用manual模式，因为token用量计算依赖模型选择，但模型选择不常变 export const promptTokenEstimate = caveman.useMemo( (prompt: string, model: string = 'gpt-4') => { // 实际项目中，这里会调用更精确的tokenizer // 例如：claude mcpservers npx 或自研tokenizer return estimateTokens(prompt, { model }); }, [], // 空依赖，因为计算逻辑不随props变化 { key: 'prompt-token-estimator', manual: true // 手动控制失效 } ); // 使用示例：在AI智能体组件中 export function AIChatInput({ onSend }: { onSend: (msg: string) => void }) { const [input, setInput] = useState(''); const estimatedTokens = promptTokenEstimate(input, 'gpt-4'); return ( <div> <textarea value={input} onChange={e => setInput(e.target.value)} /> <div className="token-counter"> {/* 实时显示预估token数 */} Estimated: {estimatedTokens} tokens </div> <button onClick={() => { onSend(input); // 发送后，手动失效缓存，因为input已变 promptTokenEstimate.invalidate(); }} > Send </button> </div> ); }

这个方案的优势：

• 复用性：所有需要token预估的组件（如flowork画布中的AI指令框、代码生成面板）都调用同一promptTokenEstimate；
• 精确性：estimateTokens库支持不同模型的tokenization规则，比硬编码准确得多；
• 可调试：caveman.inspect('prompt-token-estimator')能看到每次预估的输入prompt和结果，方便对比API实际返回的usage.total_tokens；
• 低成本：计算在前端完成，不增加API调用次数，避免failed to refresh token类错误因频繁调用token endpoint引发。

我们在一个Claude集成项目中，用此方案将token预估误差从±28%降至±3.2%，客户账单争议率下降90%。

4.3 解决flowork画布布局计算：跨组件复用昂贵计算

React画布（如flowork）的核心性能瓶颈在于布局计算：节点位置、连接线路径、碰撞检测等。这些计算复杂度高（O(n²)），且需在拖拽、缩放、增删节点时高频执行。useMemo无法跨组件复用，导致同一画布内多个视图（缩略图、属性面板、时间轴）各自重复计算。

caveman的解决方案是：为画布状态创建全局缓存，所有视图共享同一份计算结果。

// src/canvas/cache.ts import { caveman } from 'caveman'; // 画布状态缓存：输入是整个画布数据，输出是布局计算结果 export const canvasLayoutCache = caveman.useMemo( (canvasState: CanvasState) => { // 这里是真实的布局算法，简化为伪代码 return computeLayout({ nodes: canvasState.nodes, edges: canvasState.edges, viewport: canvasState.viewport }); }, [], // 依赖由调用方传入，不在这里声明 { key: 'canvas-layout-computer', // 设置TTL，防止长时间未操作后缓存过期 ttl: 300000 // 5分钟 } ); // 使用示例：在缩略图组件中 export function ThumbnailView({ canvasState }: { canvasState: CanvasState }) { const layout = canvasLayoutCache(canvasState); return ( <div className="thumbnail"> {layout.nodes.map(node => ( <div key={node.id} style={{ left: node.x / 10, top: node.y / 10 }} /> ))} </div> ); } // 在属性面板中，同样调用 export function PropertyPanel({ canvasState }: { canvasState: CanvasState }) { const layout = canvasLayoutCache(canvasState); // 复用同一缓存！ return ( <div> <h3>Node Count: {layout.nodes.length}</h3> <p>Edge Length: {layout.totalEdgeLength.toFixed(2)}</p> </div> ); }

关键点解析：

• canvasLayoutCache是一个函数，接受canvasState作为参数，内部自动处理依赖比对；
• 所有调用者共享同一缓存实例，ThumbnailView和PropertyPanel的layout变量指向同一内存地址；
• ttl: 300000确保用户离开画布5分钟后缓存自动清理，避免内存泄漏；
• 当canvasState变化时，caveman自动比对快照，仅当真正变化时才重新计算。

实测数据：在一个含200+节点的flowork画布中，此方案将布局计算耗时从平均86ms降至12ms（首次计算），后续复用为0ms；CPU占用率下降41%；拖拽帧率从42fps提升至59fps。

4.4 解决token exchange failed问题：构建健壮的认证缓存层

token exchange failed: token endpoint returned status 403 forbidden这类错误，根源常是前端缓存了过期或无效的token解析结果。caveman让我们能构建一个带健康检查、自动失效、错误隔离的认证缓存层。

// src/auth/cache.ts import { caveman } from 'caveman'; import { parseJWT, isTokenExpired } from './jwtUtils'; // 认证信息缓存：解析token并验证有效性 export const authInfoCache = caveman.useMemo( (rawToken: string) => { try { const payload = parseJWT(rawToken); // 关键：在缓存计算中做健康检查 if (isTokenExpired(payload)) { throw new Error('Token expired'); } return { userId: payload.sub, role: payload.role, permissions: payload.permissions || [], expiresAt: payload.exp * 1000 }; } catch (e) { // 计算失败时，返回null，避免缓存错误结果 console.error('[caveman] Auth token parse failed:', e); return null; } }, [], // 依赖由调用方传入 { key: 'auth-info-parser', // 手动模式，由auth service控制失效 manual: true, // 错误时返回null，而非抛出异常 onError: (error, key) => { // 不做额外处理，因为已在try-catch中处理 } } ); // 认证服务：集中管理token生命周期 export class AuthService { private static instance: AuthService; static getInstance() { if (!AuthService.instance) { AuthService.instance = new AuthService(); } return AuthService.instance; } async login(credentials: Credentials) { const token = await this.fetchToken(credentials); // 登录成功，设置缓存 authInfoCache(token); } async refreshToken() { try { const newToken = await this.api.refresh(); // 刷新成功，更新缓存 authInfoCache(newToken); } catch (e) { // 刷新失败，清除缓存并跳转登录 authInfoCache.invalidate(); window.location.href = '/login'; } } logout() { // 登出时，清除所有认证相关缓存 caveman.clearKeys(/^auth-.*/); } }

这个设计的精妙之处在于：

• 健康检查前置：isTokenExpired在缓存计算阶段就执行，确保缓存中永远不存过期token；
• 错误隔离：onError回调不中断主线程，parseJWT失败时返回null，组件可优雅降级（如显示“请重新登录”）；
• 集中控制：AuthService统一管理invalidate()时机，避免各处散落的clearTimeout或setState；
• 批量清理：caveman.clearKeys(/^auth-.*/)一键清除所有认证缓存，包括auth-info-parser、user-permissions、api-client-config等。

我们在一个医疗SaaS系统中应用此方案后，login server error: token exchange failed类错误下降92%，用户投诉“登录后页面白屏”（react native 启动白屏的前端表现）问题彻底消失。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

caveman用起来很顺，但有几个“文档里没写、社区里没人提、但实际项目中必踩”的坑。我把它们整理成速查表，并附上独家排查技巧。这些经验，来自我们团队在6个项目中累计237小时的调试实战。

5.1 问题速查表：高频问题与根因分析

5.2 独家排查技巧：三步定位缓存问题

当遇到缓存相关Bug时，不要盲目加log或重启，按以下三步高效定位：

第一步：确认缓存状态在浏览器控制台执行：

// 查看指定key的缓存详情 caveman.inspect('your-key-here'); // 查看所有缓存key列表 Object.keys(caveman._cache); // 查看缓存统计 caveman.stats();

重点关注lastUpdated和hitCount。如果lastUpdated是很久以前，说明缓存从未被使用或已失效。

第二步：模拟依赖变化手动触发一次缓存计算，观察是否命中：

// 获取当前缓存值（不触发计算） const cachedValue = caveman.get('your-key-here'); // 强制触发计算（即使缓存存在） const newValue = caveman.compute('your-key-here', () => yourCalculation()); // 比较两者 console.log('Cached:', cachedValue, 'Computed:', newValue);

如果newValue和cachedValue不同，说明依赖快照比对有问题——检查依赖中是否有Date、Math.random()等动态值。

第三步：启用调试日志在项目入口文件（如main.tsx）顶部添加：

import { caveman } from 'caveman'; // 强制启用调试（覆盖config） (caveman as any)._debug = true;

然后操作复现问题，控制台会输出详细的缓存命中/失效日志，精准定位哪一行代码触发了失效。

5.3 那些“看似合理实则危险”的用法

有些用法初看很优雅，但会埋下隐患。以下是三个被我们团队明令禁止的模式：

❌ 危险用法1：在useEffect中调用caveman.useMemo

// 错误！useEffect不是组件顶层，违反React规则 useEffect(() => { const value = caveman.useMemo(() => heavyCalc(), [deps]); // ❌ }, [deps]);

正确做法：把caveman.useMemo移到组件顶层，useEffect中只调用返回的缓存函数：

// 正确 ✅ const heavyCalcCache = caveman.useMemo(() => heavyCalc(), [deps]); useEffect(() => { const value = heavyCalcCache(); // ✅ }, [deps]);

❌ 危险用法2：缓存异步函数（Promise）

// 错误！caveman不处理Promise，会缓存pending状态 const dataCache = caveman.useMemo( () => fetch('/api/data').then(res => res.json()), // ❌ [] );

正确做法：用useMemo缓存fetch函数，用useEffect或Suspense处理异步：

// 正确 ✅ const fetchData = caveman.useMemo( () => () => fetch('/api/data').then(res => res.json()), [] ); // 然后在组件中调用 useEffect(() => { fetchData().then(setData); }, []);

❌ 危险用法3：在服务端（SSR）使用manual模式

// 错误！SSR环境无法调用invalidate() if (typeof window === 'undefined') { // 服务端，不能invalidate } const cache = caveman.useMemo(() => calc(), [], { manual: true }); // ❌

正确做法：SSR场景强制使用auto模式，或用caveman.ssr专用API：

// 正确 ✅ const cache = caveman.useMemo(() => calc(), [], { manual: typeof window !== 'undefined' });

这些坑，每一个都让我们团队多花了至少4小时调试。现在，新成员入职第一天，就会收到这份《caveman避坑手册》。

6. 性能与安全边界：caveman不是万能的，这些场景请绕道

caveman很强大，但它有明确的适用边界。强行在不合适的场景使用，不仅得不到收益，反而增加复杂度和风险。以下是三个必须绕道的场景，附带替代方案建议。

6.1 场景1：需要时间旅行调试（Time Travel Debugging）

如果你的项目重度依赖Redux DevTools的时间旅行功能（回滚action、重放state），caveman无法提供类似能力。因为它不记录state变更历史，只缓存计算结果。

替代方案：

• 对于需要调试的全局状态，继续用Redux Toolkit或Zustand；
• 用caveman只缓存那些“纯计算、无副作用、可重复执行”的函数，如formatDate()、calculateTotalPrice()、generateSVGPath()；