跳到主要内容

Next.js 笔记 · 常见问题

收录 Next.js App Router 开发中最容易踩的坑与对应的速查。 详细概念见 II_Next.js 路由笔记 / III_Next.js Server与Client组件笔记 / V_Next.js 渲染模式笔记


一、动态 API:什么会让路由变成动态​

下面这些用法都会让整个路由段变成动态渲染(不再是静态化 SSG/ISR):

用法影响
cookies()动态
headers()动态
searchParams(作为 props)动态
fetch(url, { cache: 'no-store' })这次请求不缓存
export const dynamic = 'force-dynamic'强制动态

反过来说:能不用就别用,能提到子段就用子段,否则整个 layout 链都会变动态。

例外:动态 API 也可以配合静态​

// page.tsx
import { Suspense } from 'react'
import DynamicPart from './DynamicPart'

export default function Page() {
return (
<>
<h1>静态外壳</h1> {/* 这部分仍然可被预渲染 */}
<Suspense fallback={<p>加载中...</p>}>
<DynamicPart /> {/* 动态部分包在 Suspense 里 */}
</Suspense>
</>
)
}

这就是 Streaming + 部分静态化的雏形(PPR 走得更远)。


二、cookies() / headers() 异步化​

Next.js 14 起 cookies() / headers() 返回 Promise:

// ✅ 正确(Next.js 14+)
const cookieStore = await cookies()
const session = cookieStore.get('session')

const headersList = await headers()
const userAgent = headersList.get('user-agent')

// ❌ 旧写法(13)会报错
const session = cookies().get('session')

如果看到 cookies() should be awaited 之类的报错,就是忘了 await。


三、环境变量​

前缀暴露给用途
NEXT_PUBLIC_*浏览器 + 服务端公开变量(如 API base URL)
不带前缀仅服务端密钥、数据库连接串
// .env.local
DATABASE_URL=postgres://... // 仅服务端可见
NEXT_PUBLIC_SITE_URL=https://x // 浏览器也能读

服务端组件里 process.env.DATABASE_URL 正常可用。 Client 组件里读 process.env.DATABASE_URL 是 undefined(安全)。


<Image>​

import Image from 'next/image'

<Image
src="/hero.png"
alt="封面"
width={800}
height={400}
priority // 首屏关键图片,关掉懒加载
/>
  • 自动懒加载、自动响应式、自动转 WebP
  • 必须传 width + height(或用 fill 配合 position: relative 的父容器)
  • 远程图片需要在 next.config.js 的 images.remotePatterns 配置允许的域名
import Link from 'next/link'

<Link href="/about">关于</Link>
<Link href={{ pathname: '/blog/[slug]', query: { slug: 'x' } }}>博客</Link>
<Link href="/x" prefetch={false}>不快取</Link>
<Link href="/x" replace>替换历史</Link>
  • 默认 prefetch 进入视口的链接
  • 内部链接走客户端导航,不要用 <a> 内部跳转

<Script>​

import Script from 'next/script'

<Script src="https://example.com/analytics.js" strategy="afterInteractive" />
  • strategy: beforeInteractive / afterInteractive / lazyOnload / worker

五、Middleware:在请求到达页面前跑​

middleware.ts 放在项目根目录(与 app/ 平级)或 src/ 下。

// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
// 例:检查 token
const token = request.cookies.get('token')?.value
if (!token) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}

// 限定匹配范围
export const config = {
matcher: ['/dashboard/:path*', '/api/protected/:path*'],
}

用途:鉴权、A/B 测试、地理位置重定向、添加请求头。


六、'use client' 常见误用​

误用后果正确做法
整个页面加 'use client'首屏 HTML 变空,丧失 SEO 优势顶层 Server,只把交互子树标 Client
在 Client 组件里 import Server 组件报错用 children 模式从父 Server 传入
在 Server 组件里写 onClick报错把那一行拆到 Client 子组件
'use client' 写在文件中间编译错误必须文件最顶部,import 之前
给纯展示组件加 'use client'增加 bundle 体积没必要加

七、常见错误速查​

报错原因修复
You're importing a component that imports useState. It only works in a Client ComponentServer 组件里用了 hooks加 'use client' 或拆出 Client 子组件
Event handlers cannot be passed to Client Component props给 Client 组件传了函数 prop把函数包在 Client 子组件里
cookies() should be awaited14+ 异步化await cookies()
Route ... used \searchParams` ... cannot be static`searchParams 让路由变动态显式接受动态,或用 searchParams 配合 Suspense
params should be awaited15+ 异步化const { id } = await params
Hydration failed服务端和客户端渲染不一致不要在渲染中用 Date.now() / Math.random() / window

八、文件命名规范​

位置命名备注
app/page.tsx必须小写路由入口
app/layout.tsx必须小写布局
app/_components/下划线开头私有文件夹,不被路由
组件文件PascalCaseUserCard.tsx
工具函数camelCase 或 kebab-caseformat-date.ts

九、TypeScript 类型​

路由参数​

type Props = {
params: Promise<{ slug: string }> // Next.js 15+
searchParams: Promise<{ [k: string]: string | string[] | undefined }>
}

export default async function Page({ params, searchParams }: Props) {
const { slug } = await params
const { q } = await searchParams
}

Page props 完整签名(Next.js 14)​

type Props = {
params: { slug: string }
searchParams?: { [key: string]: string | string[] | undefined }
}

环境变量类型​

// next-env.d.ts(自动生成)
/// <reference types="next" />
/// <reference types="next/image-types/global" />

自定义 env 变量类型可以在 env.d.ts 里写:

namespace NodeJS {
interface ProcessEnv {
DATABASE_URL: string
NEXT_PUBLIC_SITE_URL: string
}
}

十、构建与部署​

本地开发​

npm run dev # 默认
npm run dev --turbo # 启用 Turbopack(更快)

构建​

npm run build # 生产构建
npm run start # 跑生产服务

部署目标​

平台支持
Vercel一键,最佳体验
Node.js 自托管next start,需要 Node 18.17+
Docker用 node:18-alpine + next start
静态导出next export(注意:App Router 静态导出能力有限)

静态导出(output: 'export')​

// next.config.js
module.exports = {
output: 'export',
}
  • 把整个站生成成纯静态文件
  • 限制:不能用 Server Actions、Route Handlers(带动态参数)、cookies() / headers()、中间件
  • 适合:纯内容站、博客、文档

十一、容易忽略的小点​

  1. app/ 和 pages/ 不能共存于一个项目
  2. app/ 下所有文件都默认是"路由系统的一部分",未被识别的文件名会被忽略
  3. Server Component 里不要用 Date.now() / Math.random() —— 这会导致构建期/运行期渲染不一致
  4. Client 组件用的库(包括 UI 组件库)必须自己支持 RSC,否则会报错
  5. 'use client' 是模块级:整个文件 + 它 import 的所有东西都被传染
  6. Server Action 默认需要重新验证:写操作后记得 revalidatePath / revalidateTag
  7. Client fetch 不要绕过 Server 父组件拉首屏数据——首屏会"白一下"

十二、对应 demo​