数据获取、缓存与环境变量
本合集目录
本章目录
单册说明:本文件是卷 4 的第 7 章,可独立阅读。前置:第 6 章(App Router)。本章把数据从组件里挪到一个独立的 data 层,并回答两个必须自己拍板的问题:这份数据多久算旧?哪些配置能被浏览器看到?
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 4 · React 与 Next.js(第 7 / 8 章) |
| 前置章节 | 4.6 Next.js 的 App Router |
| 本章产出 | lib/notes.js 数据层 + 一套显式的缓存策略 + .env.local / .env.example |
| 对应代码 | data/notes.json、lib/notes.js、components/DataSourceBadge.jsx |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能说出一个变量会不会进浏览器包,并知道改了环境变量为什么要重新构建 |
4.7.1 一句话结论:服务端取数省掉一次往返,但"多久算旧"必须你说了算
先看一个反复出现的工单:
我在服务器上改了
notes.json,加了一条摘录。刷新首页,还是"已收录 3 条"。重启服务,还是 3 条。重新npm run build之后才变成 4 条。
这不是缓存坏了,是页面在构建时就已经算好了。构建的那一刻,首页被渲染成一份固定的 HTML,之后谁访问都拿这一份。数据文件改了,HTML 不会自己重算。
所以这一章的核心不是"怎么取数据"(await 一下就行),而是你知不知道自己拿到的数据是什么时候的。
4.7.2 原理与方法
在服务端取数:组件直接 await
export default async function NotesPage() {
const notes = await getNotes();
return <NoteList notes={notes} />;
}
组件是 async 的,Next 会等它 resolve 再生成 HTML。相比第 4 章那套 useEffect + 三态判断,这里少了四样东西:loading 状态、error 状态、清理函数、竞态处理。因为数据在发响应之前就取好了,浏览器收到的就是成品。
| 对比项 | 客户端取数(第 4 章) | 服务端取数(本章) |
|---|---|---|
| 首屏内容 | HTML 是空壳,要等 JS + 请求 | HTML 自带内容 |
| 请求次数 | 每个用户一次 | 每个请求一次(或构建时 0 次) |
| 密钥 | 不能碰(会进浏览器) | 可以读 |
| 加载态 | 必须自己写 | 静态时不需要,动态时用 loading.js |
| 竞态 | 必须处理 | 不存在(每次请求独立渲染) |
一个容易忽略的性能问题:串行的 await 会变成瀑布。
// 慢:两次 I/O 排队
const notes = await getNotes();
const tags = await getTags();
// 快:同时发出
const [notes, tags] = await Promise.all([getNotes(), getTags()]);
两者互不依赖时一定要并行。三个各 100 ms 的查询,串行是 300 ms,并行是 100 ms。这个差别在数据库上会被放大。
缓存有四层,别混着理解
| 层 | 缓存的是什么 | 谁控制 | 失效方式 |
|---|---|---|---|
| 浏览器 | HTML、CSS、JS、图片 | HTTP 响应头 | 强刷、换文件名 |
| 全路由缓存 | 整页的 HTML 与 RSC 结果 | dynamic / revalidate |
到期、重新构建、手动失效 |
| 数据缓存 | fetch 的结果 |
cache / next.revalidate / tag |
到期、revalidateTag |
| 请求内记忆 | 同一次渲染里重复调用同一函数 | 框架自动 | 请求结束自动清 |
需要坦白一件事:默认值在版本之间变过。 早几个版本里 fetch 默认缓存,后来改成了默认不缓存。所以网上大量"默认会缓存"的说法已经过期。
结论不是"记住新默认值",而是:在代码里写清楚你要什么。 依赖默认值的代码,会在升级时悄悄改变行为,而且没有任何报错。
| 写法 | 语义 | 适合 |
|---|---|---|
fetch(url, { cache: 'no-store' }) |
每次请求都取最新 | 用户自己的数据、频繁变动 |
fetch(url, { cache: 'force-cache' }) |
一直用缓存,直到重新构建或手动失效 | 几乎不变的配置 |
fetch(url, { next: { revalidate: 60 } }) |
60 秒内用缓存,过期后重新取 | 列表、排行榜 |
fetch(url, { next: { tags: ['notes'] } }) |
打标签,之后可精确失效 | 内容更新后要立刻刷新的页面 |
export const revalidate = 60 |
整段路由的默认策略 | 页面级统一 |
export const dynamic = 'force-dynamic' |
每次请求都重新渲染 | 强实时 |
注意:这些配置对 fetch 有效。本章的数据来自 fs.readFile,不走 fetch,所以数据缓存那一层对它不适用,起作用的是"全路由缓存"——页面整体是静态的,读文件发生在构建时。
静态还是动态:一条判断线
| 维度 | 静态生成 | 动态渲染 |
|---|---|---|
| 什么时候算 | 构建时一次 | 每次请求 |
| 首字节 | 直接发文件,最快 | 等数据源 |
| 数据新鲜度 | 到下次构建(或 revalidate 到期) | 实时 |
| 部署要求 | 可以纯静态托管 | 必须有 Node 进程 |
| 成本 | 最低 | 需要常驻服务器 |
判断线:内容对所有人都一样 → 静态;内容跟人、跟时间、跟请求参数走 → 动态。
有四类东西会让一个路由自动变成动态,哪怕你什么配置都没写:
| 用了什么 | 为什么变动态 |
|---|---|
cookies() |
结果依赖这个用户的 cookie |
headers() |
结果依赖请求头 |
searchParams |
结果依赖查询串 |
fetch(..., { cache: 'no-store' }) |
明确要求最新 |
第 4.6 章那个 /notes?tag=js 就是第三种。它没有写任何 dynamic 配置,却已经是动态路由了——因为不同 ?tag 必须给出不同结果。
怎么确认?npm run build 的输出会给每个路由标一个符号:○ 是静态,ƒ 是动态。以构建输出为准,不要凭感觉。
"我就要每次都是最新的"
三种写法,按粒度从大到小:
// 1. 整页动态
export const dynamic = 'force-dynamic';
// 2. 单次请求不缓存
const res = await fetch(url, { cache: 'no-store' });
// 3. 短周期刷新(仍然是静态,但会定期重算)
export const revalidate = 10;
怎么选:用户自己的数据(收藏、草稿)用 1 或 2;公共列表用 3;后台管理的实时看板用 1。全都设成 force-dynamic 最省心,但也最慢最贵——等于放弃了这一整章的好处。
NEXT_PUBLIC_ 的边界:一个前缀决定生死
Next 在构建时做文本替换:源码里的 process.env.NEXT_PUBLIC_API_BASE 会被替换成字面量字符串。
| 变量名 | 服务端组件能读 | 客户端组件能读 | 浏览器里能看到 |
|---|---|---|---|
DUDAO_DATA_SOURCE |
能 | 不能(是 undefined) |
否 |
NEXT_PUBLIC_DUDAO_SITE_NAME |
能 | 能 | 是,明文 |
所以规则只有一条:加了前缀,就等于把它写在了首页上。
真实事故长这样:有人把地图服务、天气接口、AI 服务的密钥写成 NEXT_PUBLIC_MAP_KEY,因为"不加前缀前端读不到"。上线后任何人打开 F12,在 JS 文件里搜 key 就能拿到,然后拿去刷他的额度。
# 构建之后自己查一遍,能搜到就说明泄了
grep -rl "sk-" .next/static | head
判断口诀:这句话能不能贴在首页上?不能,就别加前缀。
那前端确实需要调用第三方服务怎么办?两种正路:把调用放到服务端(Next 的 Route Handler 或卷 5 的 FastAPI),前端只调自己的接口;或者使用对方提供的、本来就设计成公开的、带域名限制的 key。
.env.local 与 .env.example
| 文件 | 提交到 Git | 用途 |
|---|---|---|
.env.local |
不提交 | 你本机的真实值,含密钥 |
.env.example |
提交 | 只有键名和占位符,告诉别人要填什么 |
.env |
一般不提交 | 团队共享的非敏感默认值(视约定) |
create-next-app 生成的 .gitignore 里通常有一行 .env*,它会把 .env.example 也一起忽略掉。这行要补一个例外:
.env*
!.env.example
验证方式不是"我觉得没提交",而是让 Git 回答:
git check-ignore -v .env.local # 有输出 = 被忽略,正确
git ls-files | grep env # 只应该看到 .env.example
如果 .env.local 已经被提交过,加 .gitignore 是没用的——历史里还在。要 git rm --cached .env.local 并立刻轮换那个密钥,因为按"已泄漏"处理才是安全的默认。
4.7.3 动手:把数据搬进 data 层
数据文件
新建 data/notes.json,内容就是第 6 章那个数组(JSON 里不能有注释、不能有尾逗号,字符串必须双引号):
[
{
"id": "n1",
"title": "闭包是函数和它的词法环境",
"content": "函数记住它被定义时所在的作用域,即使离开了那个作用域,仍然能访问里面的变量。",
"sourceUrl": "https://example.com/closure",
"tags": ["js"],
"createdAt": "2026-11-02"
},
{
"id": "n2",
"title": "盒模型把内容、内边距、边框、外边距分开算",
"content": "width 默认只算内容区,加上 padding 和 border 之后,元素实际占的宽度会更大。",
"sourceUrl": "https://example.com/box-model",
"tags": ["css"],
"createdAt": "2026-11-05"
},
{
"id": "n3",
"title": "effect 的清理函数在下次执行前调用",
"content": "清理不只在卸载时执行,每次依赖变化导致的重新执行之前,也会先跑一遍。",
"sourceUrl": "https://example.com/effect",
"tags": ["js", "react"],
"createdAt": "2026-11-09"
}
]
数据层:一个文件,两个数据源
lib/notes.js:
import fs from 'node:fs/promises';
import path from 'node:path';
import { notes as memoryNotes } from '@/data/memory-notes';
const filePath = path.join(process.cwd(), 'data', 'notes.json');
const source = process.env.DUDAO_DATA_SOURCE ?? 'file';
async function readAll() {
if (source === 'memory') return memoryNotes;
const raw = await fs.readFile(filePath, 'utf8');
return JSON.parse(raw);
}
export async function getNotes(tag = 'all') {
const all = await readAll();
return tag === 'all' ? all : all.filter((n) => n.tags.includes(tag));
}
export async function getNote(id) {
const all = await readAll();
return all.find((n) => String(n.id) === String(id)) ?? null;
}
export async function getTags() {
const all = await readAll();
return [...new Set(all.flatMap((n) => n.tags))];
}
把 4.6 的 data/notes.js 改名为 data/memory-notes.js(内容不变,仍是 export const notes = [...]),作为"不读磁盘"的对照组。
三个细节:
process.cwd()是项目根目录。用相对路径'data/notes.json'在开发时能跑,在生产启动目录不同时会找不到文件。- 解析失败没有 try/catch,是故意的。JSON 写错时应该立刻看到
SyntaxError,而不是被吞掉变成"没有数据"。 source在模块加载时读一次。环境变量在运行期不会变,这样写没问题;但也意味着改了.env.local必须重启。
给路由加策略
app/page.js 顶部:
export const revalidate = 60;
首页不依赖任何请求参数,可以在构建时生成,revalidate 让它每 60 秒在后台重算一次。这就是 ISR(增量静态再生成):访客拿到的始终是一份现成的 HTML,只是这份 HTML 会定期换新。
app/notes/page.js 不要加 revalidate——它读了 searchParams,已经是动态路由,写了也不会生效。这种"写了但没生效"最容易让人误判,所以宁可不写。
app/notes/[id]/page.js 同理,也不要加。它没有 generateStaticParams,Next 不知道构建时该生成哪些 id,只能等请求来了再渲染,同样是动态路由。revalidate 只对"能被静态生成"的路由有意义。
| 路由 | 类型 | 原因 |
|---|---|---|
/ |
静态 + ISR | 不依赖请求,构建时生成,60 秒刷新 |
/notes |
动态 | 读了 searchParams |
/notes/n1 |
动态 | 没告诉它有哪些 id 可以预生成 |
环境变量
.env.local:
DUDAO_DATA_SOURCE=file
NEXT_PUBLIC_DUDAO_SITE_NAME=读到
.env.example:
# 数据源:file 读 data/notes.json,memory 用内置数组
DUDAO_DATA_SOURCE=file
# 会打进浏览器包,不要放任何密钥
NEXT_PUBLIC_DUDAO_SITE_NAME=读到
一个用来"验证边界"的客户端组件
components/DataSourceBadge.jsx:
'use client';
export default function DataSourceBadge() {
return (
<p className="badge">
站点:{process.env.NEXT_PUBLIC_DUDAO_SITE_NAME}
|数据源:{process.env.DUDAO_DATA_SOURCE ?? '(浏览器看不到)'}
</p>
);
}
把它放进 app/layout.js 的页脚,然后在浏览器里看。
预期效果:
- 站点名显示"读到"——因为带
NEXT_PUBLIC_,构建时被替换成了字面量; - 数据源显示"(浏览器看不到)"——因为不带前缀的变量在客户端代码里被替换成
undefined,??兜底生效。
同一份 .env.local,在服务端组件里读 DUDAO_DATA_SOURCE 是有值的(file)。同一个变量,两个世界。
验证缓存行为
npm run build
输出里每个路由前面有一个符号:○ 是静态,ƒ 是动态。按上面的配置,你会看到 / 是 ○,/notes 和 /notes/[id] 是 ƒ。
这就是"配置之外,代码本身也在决定渲染方式":你只在首页写了一句 revalidate,另外两条路由什么都没写,却因为读了请求参数或缺少预生成清单,自动变成了动态。
然后做一次对照实验,把静态和动态放在一起看:
npm start起服务,打开首页,记下"已收录 3 条"和最近第一条的标题;- 改
data/notes.json:把 n1 的标题改掉,再往数组里加第四条; - 立刻刷新首页——还是"3 条"、旧标题。因为首页是 60 秒前的静态版本;
- 过 60 秒后再刷新——第一次可能还是"3 条",再刷一次变成"4 条"。因为 ISR 是"先给旧的,同时在后台重算"(stale-while-revalidate),第一个请求负责触发,第二个请求才吃到新结果;
- 现在打开
/notes/n1——立刻就是新标题,不用等。它是动态路由,每次请求都重新读文件。
同一个数据文件、同一次启动,两条路由给出不同的新鲜度。这就是这一章最该带走的手感。
4.7.4 三个坑
坑一:客户端组件读不到非 NEXT_PUBLIC_ 变量
症状:process.env.DUDAO_DATA_SOURCE 在浏览器里永远是 undefined,代码走默认分支;你反复确认 .env.local 写了、也重启了,就是没有。
成因:构建时只替换带前缀的变量,其余的在客户端包里被替换成 undefined。这是设计,不是 bug。
修法:先判断这个值该不该给浏览器看。该看,加 NEXT_PUBLIC_ 前缀(并确认不敏感);不该看,就把使用它的逻辑移到服务端组件或 Route Handler,让浏览器只拿结果。
坑二:把密钥写进 NEXT_PUBLIC_
症状:上线后额度被刷爆;或者安全扫描报告里写着"前端 JS 包含硬编码凭证";或者你自己在 .next/static 里 grep 到了明文。
成因:带前缀的变量会被内联进 JS 文件,等于公开发布。压缩和混淆不算保护——搜关键词就能找到。
修法:三步,顺序不能反。① 立刻在服务商后台轮换密钥(旧的已泄漏);② 去掉前缀,把调用移到服务端;③ 清理 Git 历史里的 .env 提交,并在 .gitignore 里加规则。只做第三步等于没做。
坑三:改了环境变量,页面还是旧值
症状:线上改了 NEXT_PUBLIC_ 的值,刷新无数次都没变;本地改了就生效,因为 next dev 会重启。
成因:带前缀的变量是构建时写进产物的,运行期改环境变量不会影响已经打包的 JS。静态导出更彻底——值被烧进了 HTML。
修法:改完必须重新构建并重新部署。如果值本身是给服务端读的,还要确认页面的 revalidate 没有让旧 HTML 继续被返回——两者叠加时,你会以为是环境变量没生效,其实是页面缓存。
本章验收
-
data/notes.json成为唯一数据源,lib/notes.js里没有组件代码 -
npm run build的输出里,能指出哪条路由是静态、哪条是动态,并说出原因 -
.env.local与.env.example都在,git check-ignore的结果符合预期 - 在浏览器里亲眼看到"带前缀有值、不带前缀是 undefined"
- 做完了"改数据文件 → 观察是否立刻生效"的对照实验
自测
Q1:为什么 Promise.all 在这个场景里比两次 await 快?什么情况下不能这么写?
看答案
两个查询互不依赖时,Promise.all 让它们同时发出,总耗时取最大值;串行 await 的耗时是两者相加。不能用的场景是后者依赖前者的结果,比如先查用户 id 再用 id 查订单,这时必须串行,强行并行会拿到 undefined。Q2:一个页面什么配置都没写,却变成了动态渲染,可能的原因有哪些?
看答案
它用了 cookies()、headers()、searchParams,或者内部有 cache: 'no-store' 的 fetch。这些 API 让结果依赖具体请求,框架无法在构建时算出一份通用结果,只能每次渲染。用 npm run build 的输出可以确认。Q3:.env.local 已经被提交到 Git 了,现在加进 .gitignore 还有用吗?
看答案
对未来的提交有用,但对已经提交的历史没用——任何人 clone 下来都能翻到旧版本。正确顺序是:先在服务商处轮换密钥(假定已泄漏),再 git rm --cached 把文件移出索引并提交,最后才补 .gitignore。轮换永远排第一,因为历史清理很难做到彻底。下一步
数据层有了,缓存策略也定了。最后一步是把它放到公网:一套方案需要一台常驻的 Node 进程,另一套只要一堆静态文件。下一章把两种都跑一遍,然后给出选择依据。