企业官网建设流程全解析

• 前端
• UI组件

函数结果缓存（memoization）是 JavaScript 性能优化中最基础也最有效的手段之一。本文围绕本仓库.claude/skills/vercel-react-best-practices技能集中 js-cache-function-results.md 这一条规则展开，讲解"当同一函数在渲染期间被反复以相同输入调用时，用模块级Map缓存其结果"的完整实践：包括反模式与正解代码、单值函数缓存范式、缓存失效策略、以及它与useMemo、TanStack Query 等上层缓存机制的层次关系。读完本文，你将能在 next-shadcn-dashboard-starter 这类 Next.js 仪表盘项目中，精准识别并消除渲染热路径上的冗余计算，写出对高频渲染更友好的组件代码。

规则定位：来自 Vercel 工程实践的 JavaScript 性能准则

这条规则是vercel-react-best-practices技能集（SKILL.md）中的一员。该技能集由 Vercel 工程团队维护，共含 64 条规则、覆盖 8 大性能类别，按预期收益排序。本规则的文件头（frontmatter）给出了精确定位：

根据 _sections.md 的分类，js-前缀属于Section 7 JavaScript Performance（JavaScript 性能），该分类的整体定位是"针对热路径（hot path）的微优化，积少成多也能带来可观的收益"。换句话说，这类优化不追求单点爆发，而是让每一处高频执行的小函数都变得便宜。

规则末尾还注明其灵感来源：Vercel 工程团队在复盘Vercel Dashboard 性能翻倍的公开分享中，将"缓存重复计算结果"列为了核心手段之一（原文以 Reference 形式给出外部链接，本文不展开外部地址）。

反模式：在渲染循环内重复执行昂贵函数

规则的"错误示例"非常典型——在map循环体内直接调用纯函数，对相同的输入反复计算：

function ProjectList({ projects }: { projects: Project[] }) { return ( <div> {projects.map(project => { // slugify() called 100+ times for same project names const slug = slugify(project.name) return <ProjectCard key={project.id} slug={slug} /> })} </div> ) }

问题有两层：

1. 单次渲染内的重复计算：projects列表里往往存在大量重名项目，slugify(project.name)对相同的项目名会计算 100 次以上，而结果完全一致；
2. 多次渲染间的重复计算：只要父组件因任何状态变化触发重渲染，这 100 多次slugify调用就会全部重来一遍。列表越长、渲染越频繁，浪费越严重。

slugify（把名称转成 URL 友好的 slug 字符串）这类纯函数通常是幂等的——同一输入永远产生同一输出——这正是缓存能生效的前提。

正解一：模块级 Map 缓存

规则给出的正确写法是在模块作用域声明一个Map，用输入作为键、计算结果作为值，实现"查表优先"：

// Module-level cache const slugifyCache = new Map<string, string>() function cachedSlugify(text: string): string { if (slugifyCache.has(text)) { return slugifyCache.get(text)! } const result = slugify(text) slugifyCache.set(text, result) return result } function ProjectList({ projects }: { projects: Project[] }) { return ( <div> {projects.map(project => { // Computed only once per unique project name const slug = cachedSlugify(project.name) return <ProjectCard key={project.id} slug={slug} /> })} </div> ) }

对比可以看出：

• cachedSlugify是slugify的薄封装，对外接口不变，调用方改动极小；
• 键是输入字符串，值是计算结果，Map.has/Map.get/Map.set均为O(1)复杂度，查表成本可忽略；
• 缓存位于模块级，生命周期与模块实例相同，跨渲染、跨组件实例、甚至跨页面路由（SPA 场景下模块不会重复执行）都能复用。

补充说明：在 ESLint/构建层面，TypeScript 可通过Map.get返回值非空断言（!）来规避get可能返回undefined的类型问题；更严谨的写法是const cached = cache.get(text); if (cached !== undefined) return cached;，对字符串值而言两种写法等价。

正解二：单值函数的极简缓存模式

当缓存的键只有一个（即整个函数只依赖一个可枚举的输入状态）时，Map略显冗余，规则给出了更精简的"单槽缓存"写法：

let isLoggedInCache: boolean | null = null; function isLoggedIn(): boolean { if (isLoggedInCache !== null) { return isLoggedInCache; } isLoggedInCache = document.cookie.includes('auth='); return isLoggedInCache; } // Clear cache when auth changes function onAuthChange() { isLoggedInCache = null; }

这个模式的精妙之处在于用null作为"未缓存"哨兵：

• 首次调用时缓存为空（null），执行真正的判断（这里是一次同步的document.cookie字符串扫描）并写入结果；
• 此后每次调用直接返回已缓存的布尔值，全程零计算；
• 当认证状态变化时（登出、登录、Cookie 更新），调用onAuthChange()把缓存重置为null，下次调用自然重新计算。

这里需要注意一个边界：如果函数本身合法的返回值就是null，就不能再用null做哨兵，需要改用Map或独立的has标志位——这也是规则推荐默认使用Map的原因之一。

核心原则：用 Map，不用 Hook

规则特别强调了一句容易被忽略的结论："Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components."（用 Map 而非 Hook，这样它能处处生效：工具函数、事件处理器，而不仅仅是 React 组件。）

这条原则值得展开理解：

• useMemo、useRef等 Hook 只能在 React 组件或自定义 Hook 内调用，函数体内的条件分支中不可用，且语义绑定了"组件实例"的生命周期；
• 缓存的本意是"结果与输入相关，与调用者无关"，模块级Map天然是跨组件实例、跨模块共享的；
• 工具函数（如slugify、formatDate）、事件处理器（如点击、键盘监听）里同样存在重复调用，这些场景根本无法使用 Hook。

参考对比：本仓库 src/lib/query-client.ts 中的 TanStack Query 客户端也采用了同样的模块级单例思想——browserQueryClient以模块级变量保存，客户端（浏览器环境）首次调用getQueryClient()时创建并复用同一个实例，避免每次渲染都新建QueryClient。这与"模块级共享、避免重复创建"的缓存哲学一脉相承。

缓存失效：外部变化时必须主动清空

函数结果缓存的头号风险是数据一致性——当缓存所依赖的底层数据在模块外部发生变化时，缓存会返回过期结果。规则的单值模式通过onAuthChange()展示了主动失效的基本思路；同技能集的姊妹规则 js-cache-storage.md 对缓存失效给出了更系统的方案：

监听跨标签页的 storage 变更：

window.addEventListener('storage', (e) => { if (e.key) storageCache.delete(e.key); });

页面重新可见时整体失效：

document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') { storageCache.clear(); } });

这些事件适用于"数据可能被其他标签页或服务器修改"的场景（localStorage、sessionStorage、服务端设置的 Cookie 都属于此类）。设计函数缓存时，应遵循两条经验法则：

1. 只缓存幂等纯函数：输出仅由输入决定、无副作用，是缓存安全的前提；
2. 为每个缓存配备失效出口：至少提供"清空/重置"函数，供状态变更时显式调用，如上面的onAuthChange。

与 useMemo、TanStack Query 的层次关系：缓存的不同粒度

为了避免把这条规则误用成"所有计算一律上 Map"，需要厘清缓存机制的层次：

本仓库提供了数据层缓存的真实参照：src/lib/query-client.ts为QueryClient设置了staleTime: 60 * 1000（数据 60 秒内视为新鲜，重复查询直接复用），并通过 query-provider.tsx 注入组件树。这对应技能集中 client-swr-dedup.md 描述的"多个组件实例共享一次请求"模式——它缓存的是昂贵 I/O（网络请求）的结果，而本规则缓存的是昂贵 CPU（纯函数计算）的结果。二者并不冲突，而是各管一层：Query 缓存解决"数据要不要重新拉取"，函数缓存解决"拿到的数据要不要重新加工"。

仓库源码佐证：Map 缓存在本项目中的真实落点

以下三处源码展示了与规则同源的Map用法，可作为落地参照：

1. 按字段分组错误：src/hooks/use-stepper.tsx

use-stepper.tsx 在表单校验错误处理中，用new Map<string, string[]>()将 issues 按字段路径分组，随后针对每个字段单独处理。这正是"用 Map 把多次 O(n) 扫描合并为一次 O(n) 建表 + 多次 O(1) 取值"的索引思路（对应同技能集 js-index-maps.md："Build Index Maps for Repeated Lookups"，构建一次索引，之后每次查找都是 O(1)，1000 订单 × 1000 用户场景下可从 100 万次操作降到 2000 次）。

2. 错误消息去重：src/components/ui/field.tsx

field.tsx 中用[...new Map(errors.map((error) => [error?.message, error])).values()]对重复的错误消息去重——利用Map的键唯一性，消息相同的错误只保留一条。这是"以消息为键、错误对象为值"的缓存式去重，同样展示了对Map键值语义的活用。

3. 昂贵 I/O 的缓存动机：src/constants/mock-api.ts

mock-api.ts 通过delay(ms)人为模拟网络延迟，例如列表接口await delay(1000)（1 秒）、getProductById更是await delay(3000)（第 153 行）来模拟慢接口。这直观说明了为什么"重复调用同一昂贵操作"是真实存在的性能痛点——数据层延迟无法消除时，至少应保证同一结果不被反复计算或反复请求。

4. 可进一步优化的机会：src/lib/format.ts

format.ts 的formatDate每次调用都会new Intl.DateTimeFormat('en-US', ...)构造一个新的格式化器实例，而Intl.DateTimeFormat的实例化是出了名的昂贵操作。如果某组件在渲染中对大量日期调用formatDate，完全可以套用本规则：把格式化器实例缓存到模块级 Map（以opts的序列化结果为键），或至少把默认选项的实例提升为模块常量。这是一个与仓库源码直接对应的、立即可落地的优化点（注意：这是基于规则推导出的优化建议，仓库当前实现并未缓存）。

相关规则家族：JavaScript 性能优化的完整工具箱

本规则不是孤立的，同属 Section 7 的姊妹规则构成了"缓存与查找优化"的完整工具箱，可一并阅读：

适用边界与注意事项

函数结果缓存并非万能，需要守住几条边界：

• 仅缓存幂等纯函数：函数不得依赖可变外部状态（时间、随机数、非参数化的全局状态），否则缓存会污染结果；
• 注意键的规模：Map以输入为键，如果输入组合爆炸（如连续值、对象引用），缓存会失去命中率甚至造成内存增长。规则的示例选择字符串键正是为了稳定命中；
• 需要失效机制：如本文"缓存失效"小节所述，底层数据可被外部修改时，务必提供清空出口；
• 收益与复杂度权衡：impact 等级为 MEDIUM，适合"同一函数在渲染中被重复调用"的场景；单次调用、输入几乎不重复的函数不值得引入缓存，避免过度设计。

小结

从slugify的 100 次重复计算，到isLoggedIn的单槽缓存，再到onAuthChange的失效机制，js-cache-function-results这条规则给出的其实是一套完整的方法论：用模块级Map做键值缓存，让纯函数在相同输入下只计算一次；用显式失效函数对抗数据变更；用"Map 而非 Hook"的原则让缓存突破 React 组件的边界。在本仓库的实战语境下，它可以与 query-client.ts 的全局数据缓存、useMemo的组件内派生值形成三层防护，配合 js-cache-storage.md 等姊妹规则，构成一份可以照抄进任何 Next.js 仪表盘项目的"免重复计算"清单。

• 前端
• UI组件