跳到正文
零到全栈 · 卷 4 · 从页面到应用

数据获取、缓存与环境变量

本合集目录
本章目录

单册说明:本文件是卷 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,另外两条路由什么都没写,却因为读了请求参数或缺少预生成清单,自动变成了动态。

然后做一次对照实验,把静态和动态放在一起看:

  1. npm start 起服务,打开首页,记下"已收录 3 条"和最近第一条的标题;
  2. 改 data/notes.json:把 n1 的标题改掉,再往数组里加第四条;
  3. 立刻刷新首页——还是"3 条"、旧标题。因为首页是 60 秒前的静态版本;
  4. 过 60 秒后再刷新——第一次可能还是"3 条",再刷一次变成"4 条"。因为 ISR 是"先给旧的,同时在后台重算"(stale-while-revalidate),第一个请求负责触发,第二个请求才吃到新结果;
  5. 现在打开 /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 进程,另一套只要一堆静态文件。下一章把两种都跑一遍,然后给出选择依据。

→ 卷4-08-两种上线方式.md