企业官网建设流程全解析

刚把项目升到 Next.js 16 时，最让我在意的不是 Turbopack，而是 Cache Components 这套新缓存策略到底有没有真正工作。打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 拿一把 Key，让 Claude Code 通过 TaoToken 读一遍 next.config.ts 和 app/page.tsx，把 “use cache” 是否生效的依据一条条列出来，比对着日志猜省事得多。Cache Components 确实让缓存从“玄学”变“显式”，但显式只代表代码里写了，不代表框架真的按你的意图在缓存。cacheComponents、revalidateTag、页面顶部的 “use cache”，三层都对齐时，缓存才是可控的；任何一层对不上，就会出现“我明明改了配置，线上还是旧数据”的错觉。这篇就把排查顺序拆开讲，从拿 Key 到看响应头，走完整条链路。

1. Cache Components 的“玄学”回归：改了两行配置，页面还是旧数据

1.1 从“use cache”到 cacheComponents：两层条件缺一不可

Next.js 16 把缓存门槛降低了：只要在文件顶部写"use cache"，并在 next.config.ts 里打开 cacheComponents，页面或异步函数就会被缓存。原文里说这是对“玄学缓存”的一次拨乱反正，实际用下来也确实如此——但“确实如此”的前提是两层条件同时成立，缺一不可。

第一层是编译期条件：next.config.ts 里的 cacheComponents 必须显式为 true，Turbopack 才会把带"use cache"的文件纳入缓存编译路径。第二层是源码标注条件：页面组件或数据获取函数顶部必须真的有"use cache"，而不是写在注释里或写错位置。很多“配置没生效”的场景，其实是第二层出了问题：文件改名、指令写进服务端组件之外的子组件、或者 IDE 自动格式化把指令挪到了 import 之后。

这类问题靠肉眼检查容易漏。更合理的做法是让 Claude Code 把读到的内容逐条核对，而不是凭感觉下结论。

1.2 排查第一步：让模型先读磁盘上的真实配置

这里的重点是把项目文件交给 Claude Code，让它按要求输出核查清单。注意，这个动作是读取文件并解释，不是让 Claude Code 去修改生产代码。我通常在项目根目录下让 Claude Code 执行类似这样的任务：

请读取 next.config.ts 和 app/page.tsx，检查三件事：cacheComponents 是否开启；page.tsx 顶部是否包含 "use cache" 指令；组件里是否直接调用了数据库查询或 fetch，导致缓存策略与数据变更频率不匹配。输出一份 Markdown 清单，标明每项是“已配置/未配置/需确认”。

这样做的好处是，Claude Code 会基于实际文件内容回答，而不是背文档。它会把 next.config.ts 的代码摘出来，标注 cacheComponents: true 的位置，然后对 page.tsx 给出是否命中缓存条件的判断。这一步结束后，我们才进入真正的验证环节。如果项目里同时存在多个 next.config 相关文件，它还会提醒你哪个目录下的配置正在被优先加载。

1.3 一个容易被忽略的细节：React Compiler 也会改动组件行为

原文重点介绍了 React Compiler 的稳定支持，它会自动对组件进行记忆化。React Compiler 处理的是重复渲染层面的优化，与 Cache Components 处理的数据/页面缓存属于两条不同路径。但两者叠加时有一个注意点：如果"use memo"所在的组件内部写了副作用，编译器可能调整执行时机，从而让缓存页面的日志顺序看起来异常。排查时如果发现页面输出正常但日志顺序不对，别急着怀疑缓存配置，先让 Claude Code 检查 reactCompiler 是否开启。

2. 准备 TaoToken Key，并让 Claude Code 走统一 API 通道

2.1 在官网创建 Key 与套餐

要让 Claude Code 执行上面的检查，先得有可用的模型通道。打开 TaoToken 注册并创建 API Key：登录后进入控制台的 API Keys 页面，点击创建，把生成的 Key 复制保存。模型 ID 不用背，页面里的模型广场会列出当前可用的模型名称，以那里显示的为准。

如果只是临时排查，用对话额度即可；如果接下来几天都要让 Claude Code 改 Next.js 项目，建议在 Coding Plan 页看下套餐是否更划算。注意，这一页只管账户和套餐，接口地址在下一节配置中单独填，两者不要混在一起看。要是手上同时维护好几个项目，建议每个项目单独建一把 Key，之后在控制台看用量时能直接分清是哪个项目消耗得多，排查成本会低不少。

2.2 ~/.claude/settings.json：把 Base URL 和 Key 写进环境变量

Claude Code 读取 ~/.claude/settings.json 中的 env 字段作为运行时环境变量。配置如下，也可以直接设置 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 三个环境变量，效果一样：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "你的模型ID" } }

强调三件事。第一，Base URL 是 https://taotoken.net/api，结尾不要加 /v1。Claude Code 会自动拼接 Anthropic 协议路径；如果照抄官方文档把 /v1 也填进去，反而会出现 404。第二，YOUR_API_KEY 替换成上面创建的那把 Key，不要留占位符。第三，ANTHROPIC_MODEL 填哪个模型 ID，以模型广场当时列表为准，别填一个印象里的旧名字。

2.3 快速验证通道连通

保存 settings.json 后，在项目目录里执行一句最简单的 Claude Code 指令：

claude -p "用一句话说明你当前使用的模型ID"

如果返回正常，说明统一 API 通道已经通。之后所有涉及 Next.js 16 的排查，都可以在这一通道下进行。如果这一步就报错，先不要急着排查缓存，按第 5 节的报错对照把认证和模型 ID 两个变量排除掉。这一步能确定工具链是好的，后面的代码分析才有基础。

3. 让 Claude Code 核对 next.config.ts：cacheComponents 是否真的进入构建

3.1 用提示词拿到配置核查清单

在项目根目录执行 Claude Code 时，可以这样描述任务，这是我本地跑过的提示词，可以直接复制：

请读取项目根目录的 next.config.ts，重点核查 cacheComponents 和 reactCompiler 两个开关。如果 cacheComponents 为 true，把该行代码和文件完整路径一起列出来；如果你认为这个配置可能被其他配置项覆盖，请说明理由。

Claude Code 会给出一份带路径和行号的清单。此时你会发现它不只读 next.config.ts，还会去看 tsconfig、package.json，甚至检查项目里是否有多个 next.config 文件。这正是需要确认的地方：有时根目录配置没问题，但 monorepo 子包里的 next.config 覆盖了它。如果项目配置了 Next.js DevTools MCP，Claude Code 还能额外拿到路由结构和缓存策略的上下文，但最终判断仍要以实际响应头为准。

3.2 从配置文件到构建产物：本地日志怎么读

配置写了对不对，最终要看构建输出和运行日志。Next.js 16 用 Turbopack 作为默认打包工具后，本地启动命令没有变化：

npm run dev

Turbopack 的日志比 Webpack 简练，但 Cache Components 相关的信息会出现在编译输出的几个关键位置。让 Claude Code 帮你盯日志时，可以给它一个明确的任务：

我在终端执行 npm run dev，启动完成后会把日志粘贴给你。请判断是否存在与 cacheComponents 相关的警告或错误；如果存在，指出具体是哪一行配置触发，并给出修改建议。

这一步的要点是：Claude Code 不直接执行命令，它负责解释读者贴回来的输出。这样既符合工具边界，也能避免模型在错误目录下启动一个依赖缺失的进程。

3.3 Turbopack 稳定版带来的间接影响

Turbopack 稳定版是 Next.js 16 的另一个大变化。它影响的不只是构建速度，还可能改变模块解析顺序，进而影响"use cache"指令的执行路径。如果升级后页面缓存表现和 15 不同，先别急着怀疑 API，让 Claude Code 对照 next.config.ts 和 package.json 中 next 版本，确认构建器确实是 Turbopack，再继续往下查。

还有一个容易漏掉的点：Turbopack 默认开启持久化缓存，跨会话复用编译产物。如果之前的产物启用了 cacheComponents，而这次把配置关掉了，开发服务器可能短暂表现异常。此时执行rm -rf .next再重新启动，往往比反复改配置更有效。这个操作本身很轻，适合在排查初期就做掉。

4. 用响应头和日志验证：缓存到底有没有命中

4.1 页面级与函数级缓存的不同表现

在 Next.js 16 中，"use cache"可以出现在两个位置：页面组件顶部，或者异步函数顶部。页面级的缓存会让整条路由的渲染结果被复用；函数级的缓存只缓存数据获取或计算部分，HTML 仍在每次请求时生成。排查时要先分清自己属于哪一种，否则容易把合理行为误判成 bug。

让 Claude Code 读取 app 目录下的文件结构，它会根据目录层级和指令位置给出判断。如果"use cache"写在 lib/data.ts 的 getPosts 上，而 page.tsx 没有标记，那么页面本身不会被整体缓存，只有 getPosts 的结果会命中缓存。这是设计行为，不是配置遗漏。

4.2 curl 看响应头：用缓存标记说话

配置是否生效，最终看响应头。启动本地服务后执行：

curl -I http://localhost:3000

在响应头里寻找与缓存相关的字段。Next.js 16 会在命中缓存时返回对应的缓存标记，未命中时则不会有。把完整响应头贴给 Claude Code，它会告诉你当前页面属于哪一类缓存状态，以及 revalidateTag 的设定是否合理。不要只看页面内容对不对，响应头才是判定缓存的直接证据。

4.3 如果页面还是旧数据：revalidateTag 的标签对齐

最常见的场景是：改完了 CMS 里的文章，页面还是旧的。这时让 Claude Code 检查代码里是否调用了 revalidateTag 或 updateTag，并核对标签名称是否和数据变更处一致。标签字符串错一个字母，缓存就不会被主动失效，现象就是“旧的还在”。Claude Code 可以把所有出现 revalidateTag 的位置列出来，逐个比对标签名。

原始文章里提到 revalidateTag("posts", "hours") 这类的用法，还引入了 updateTag 来直接更新缓存而无需重新请求源数据。实际使用时，第二个参数（过期时间）写法要和缓存配置匹配，否则会出现“明明调了 revalidate，页面还是旧”的错觉。Claude Code 的价值就是把这些参数间的耦合关系摆到明面上，让你一次看出是标签不一致、过期时间太短，还是缓存根本没启用。

5. 排障对照：认证失败、模型 ID 错误与 proxy.ts 改名

5.1 401 与模型 ID 不存在

配好 Claude Code 后第一次调用，如果返回 401，优先检查 settings.json 里的 ANTHROPIC_AUTH_TOKEN 是否真的换成了自己的 Key，以及 Key 是否在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建。其次检查 ANTHROPIC_MODEL 填的模型 ID 是否在当前模型广场列表中。模型 ID 属于易变信息，升级或调整后名称可能变化，以页面显示为准。

5.2 Base URL 多了 /v1 引发的 404

Claude Code 自己会拼 /v1 路径，所以 Base URL 只需写到 https://taotoken.net/api。如果填成 https://taotoken.net/api/v1，请求会打到不存在的路径上，表现就是 404 而不是 401。这个错误和模型 ID 写错还不一样：401 说明通道通了、身份没通过；404 说明地址没对上。把这两种状态区分开，排查速度会快很多。

5.3 proxy.ts 改名带来的一处小坑

Next.js 16 把 middleware.ts 更名为 proxy.ts。升级项目时如果直接把旧文件名留在根目录，新框架不一定报错，但代理逻辑可能不生效，进而影响本地开发的登录态和重定向。Claude Code 在读取文件结构时，如果发现同时存在 middleware.ts 和 proxy.ts，会提示你确认哪个生效。这个来自文件系统的判断，比翻文档更贴近你的项目现状。除此之外，升级向导里提到的 params 必须异步、Node.js 版本下限这些变更，也可以让 Claude Code 一次性检查 package.json 里的 engines 字段和目录结构，避免旧写法在运行时才炸。

6. 跑通之后：去控制台对一下调用记录，再决定要不要长期用

6.1 用模型对话验证同一把 Key

到此，排查流程已经走完一轮。如果之后还想确认问题是否出在 Claude Code 的解析环节，而不是通道或缓存配置本身，可以在 TaoToken 模型对话 里用同一把 Key 发一条消息，看同样的提示词在网页对话里的回答是否一致。这一步能帮你把“通道问题”和“模型提示词问题”分开，也为后续花时间调优提示词提供依据。

6.2 控制台看用量，并按需选择套餐

配置保存并跑完后，可以到 控制台 API Keys 查看这把 Key 的调用记录，确认刚才的排查请求确实被记账了。若接下来要把 Claude Code 作为主力工具长期使用，可以先在 Coding Plan 看套餐是否更合适。Claude Code 的环境变量写法还可以参考 Claude Code 接入文档，之后换到其他项目时对照着改就行。

6.3 最后一点体会

Next.js 16 的缓存不再是黑盒，但“不再黑盒”的前提是你愿意花十分钟验证。让 Claude Code 读取真实文件、把命令输出贴回对话，比直接问“为什么缓存没生效”有效得多。每次遇到诡异缓存问题，我都会按这个顺序走一遍：检查 cacheComponents 开关、确认 use cache 位置、curl 看响应头、核对 revalidateTag 标签名。四步下来，绝大多数“玄学”都会变成可解释的具体原因。