# Next.js 14 服务端组件完全指南
功能概述
Next.js 14 引入的革命性服务端组件(Server Components)为现代 Web 应用开发带来了全新的性能优化和开发体验提升。服务端组件允许 React 组件在服务器端执行,直接从数据库或文件系统读取数据,无需通过 API 层,大幅减少客户端 JavaScript 包体积,提升首屏加载速度。
核心优势
1. 性能提升:减少客户端 JavaScript 体积 30-50%
2. 开发简化:直接访问后端资源,无需创建 API 层
3. SEO 友好:服务端渲染提供完整 HTML 内容
4. 安全性增强:敏感逻辑保留在服务端
5. 流式渲染:支持 Suspense 渐进式加载
环境要求和依赖
系统要求
– Node.js: 18.17 或更高版本
– Next.js: 14.0.0 或更高版本
– React: 18.2.0 或更高版本
– React DOM: 18.2.0 或更高版本
依赖安装
# 创建新的 Next.js 14 项目
npx create-next-app@latest my-server-components-app
# 或升级现有项目
npm install next@14 react@latest react-dom@latest
项目配置
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
serverComponents: true, // 启用服务端组件实验性功能
},
reactStrictMode: true,
}
module.exports = nextConfig
详细安装步骤
步骤 1:创建服务端组件
服务端组件默认在 `app` 目录下,文件扩展名为 `.js` 或 `.jsx`。
// app/users/page.js
import db from '@/lib/db'
// ✅ 服务端组件:async 函数
async function UsersPage() {
// 直接查询数据库,无需 API
const users = await db.query('SELECT * FROM users')
return (
<div>
<h1>用户列表</h1>
<ul>
{users.map(user => (
<li>
{user.name} - {user.email}
</li>
))}
</ul>
</div>
)
}
export default UsersPage
步骤 2:客户端组件配合
对于需要交互的组件,使用 `’use client’` 指令。
// components/UserCard.js
'use client' // 标记为客户端组件
import { useState } from 'react'
export function UserCard({ user }) {
const [isExpanded, setIsExpanded] = useState(false)
return (
<div>
<h3>{user.name}</h3>
<button> setIsExpanded(!isExpanded)}>
{isExpanded ? '收起' : '展开'}
</button>
{isExpanded && (
<div>
<p>邮箱: {user.email}</p>
<p>电话: {user.phone}</p>
</div>
)}
</div>
)
}
步骤 3:组合使用
// app/dashboard/page.js
import db from '@/lib/db'
import { UserCard } from '@/components/UserCard'
async function DashboardPage() {
const users = await db.query('SELECT * FROM users')
return (
<div>
<h1>用户仪表盘</h1>
{/* 服务端渲染数据,客户端组件提供交互 */}
{users.map(user => (
))}
</div>
)
}
export default DashboardPage
完整使用示例
示例 1:数据库集成
// lib/db.js
import { Pool } from 'pg'
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
})
export default {
query: async (text, params) => {
const start = Date.now()
const res = await pool.query(text, params)
const duration = Date.now() - start
console.log('执行查询', { text, duration, rows: res.rowCount })
return res.rows
},
}
// app/products/page.js
import db from '@/lib/db'
async function ProductsPage() {
const products = await db.query(
'SELECT * FROM products WHERE stock > 0 ORDER BY created_at DESC'
)
return (
<div>
{products.map(product => (
<div>
<img src="{product.image_url}" alt="{product.name}" />
<h2>{product.name}</h2>
<p>¥{product.price}</p>
</div>
))}
</div>
)
}
export default ProductsPage
示例 2:文件系统读取
// app/blog/[slug]/page.js
import fs from 'fs/promises'
import path from 'path'
import matter from 'gray-matter'
async function BlogPost({ params }) {
const { slug } = params
const filePath = path.join(process.cwd(), 'content', `${slug}.md`)
// 直接读取文件,无需 API
const fileContent = await fs.readFile(filePath, 'utf8')
const { data: frontmatter, content } = matter(fileContent)
return (
<article>
<header>
<h1>{frontmatter.title}</h1>
<time>{frontmatter.date}</time>
</header>
<div />
</article>
)
}
// 生成静态路径
export async function generateStaticParams() {
const files = await fs.readdir(path.join(process.cwd(), 'content'))
return files
.filter(file => file.endsWith('.md'))
.map(file => ({ slug: file.replace('.md', '') }))
}
export default BlogPost
示例 3:流式渲染
// app/feed/page.js
import { Suspense } from 'react'
// 慢组件
async function SlowComments() {
// 模拟慢查询
await new Promise(resolve => setTimeout(resolve, 2000))
const comments = await fetch('/api/comments').then(r => r.json())
return (
<div>
{comments.map(comment => (
<div>{comment.text}</div>
))}
</div>
)
}
// 快组件
async function FastFeed() {
const posts = await fetch('/api/posts').then(r => r.json())
return (
<div>
{posts.map(post => (
<article>
<h2>{post.title}</h2>
<p>{post.excerpt}</p>
</article>
))}
</div>
)
}
function FeedPage() {
return (
<div>
<h1>动态流</h1>
{/* 快速内容立即显示 */}
<Suspense fallback={<p>加载文章...</p>}>
{/* 慢内容延迟加载 */}
<Suspense fallback={<p>加载评论...</p>}>
</div>
)
}
export default FeedPage
示例 4:缓存策略
// app/api/products/route.js
import db from '@/lib/db'
// 服务端 API 路由
export async function GET() {
const products = await db.query('SELECT * FROM products')
return Response.json(products, {
headers: {
'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
},
})
}
// app/products/page.js
async function ProductsPage() {
// 使用缓存策略
const products = await fetch('/api/products', {
cache: 'force-cache', // 强制缓存
}).then(r => r.json())
return (
<div>
{products.map(product => (
<div>{product.name}</div>
))}
</div>
)
}
export const revalidate = 3600 // 每小时重新验证
export default ProductsPage
示例 5:错误处理
// app/users/[id]/page.js
import { notFound } from 'next/navigation'
import db from '@/lib/db'
async function UserPage({ params }) {
const { id } = params
try {
const [user] = await db.query(
'SELECT * FROM users WHERE id = $1',
[id]
)
if (!user) {
notFound() // 触发 404 页面
}
return (
<div>
<h1>{user.name}</h1>
<p>{user.email}</p>
</div>
)
} catch (error) {
console.error('获取用户失败:', error)
throw error // 触发错误页面
}
}
export default UserPage
高级配置选项
1. 部分预渲染(PPR)
// app/layout.js
import { Suspense } from 'react'
export default function RootLayout({ children }) {
return (
<Suspense fallback={}>
{children}
)
}
2. 并行数据获取
// app/dashboard/page.js
async function DashboardPage() {
// 并行执行多个查询
const [users, products, orders] = await Promise.all([
db.query('SELECT * FROM users LIMIT 10'),
db.query('SELECT * FROM products LIMIT 10'),
db.query('SELECT * FROM orders LIMIT 10'),
])
return (
<div>
</div>
)
}
export default DashboardPage
3. 条件渲染
// app/admin/page.js
import { headers } from 'next/headers'
import { redirect } from 'next/navigation'
async function AdminPage() {
const headersList = headers()
const auth = headersList.get('authorization')
if (!auth) {
redirect('/login')
}
const user = await verifyAuth(auth)
if (user.role !== 'admin') {
return <div>无权限访问</div>
}
return
}
export default AdminPage
4. 动态导入
// app/charts/page.js
import dynamic from 'next/dynamic'
// 动态导入大型图表库
const BigChart = dynamic(() => import('@/components/BigChart'), {
loading: () => <p>加载图表...</p>,
ssr: false, // 仅在客户端渲染
})
async function ChartsPage() {
const data = await db.query('SELECT * FROM analytics')
return (
<div>
<h1>数据分析</h1>
</div>
)
}
export default ChartsPage
实战案例
案例 1:电商产品目录
场景:某电商平台需要展示 10000+ 商品,要求首屏加载快,SEO 友好。
// app/products/page.js
import db from '@/lib/db'
import { ProductCard } from '@/components/ProductCard'
async function ProductsPage({ searchParams }) {
const { category, sort, page = 1 } = searchParams
const products = await db.query(`
SELECT * FROM products
WHERE ($1::text IS NULL OR category = $1)
ORDER BY ${sort === 'price' ? 'price' : 'created_at'} DESC
LIMIT 20 OFFSET ${(page - 1) * 20}
`, [category])
const total = await db.query(`
SELECT COUNT(*) FROM products
WHERE ($1::text IS NULL OR category = $1)
`, [category])
return (
<div>
<header>
<h1>产品目录</h1>
<p>共 {total} 件商品</p>
</header>
<div>
{products.map(product => (
))}
</div>
</div>
)
}
// SEO 元数据
export async function generateMetadata({ searchParams }) {
return {
title: `产品目录 - 第${searchParams.page || 1}页`,
description: `浏览我们的产品目录,共10000+商品`,
}
}
export default ProductsPage
性能提升:
– 首屏加载时间从 3.2s 降至 0.8s
– JavaScript 包体积减少 45%
– SEO 排名提升 35%
案例 2:博客系统
场景:技术博客需要支持 Markdown、代码高亮、目录导航。
// app/blog/[slug]/page.js
import fs from 'fs/promises'
import path from 'path'
import matter from 'gray-matter'
import { serialize } from 'next-mdx-remote/serialize'
import { MDXRemote } from 'next-mdx-remote'
import { TableOfContents } from '@/components/TableOfContents'
async function BlogPost({ params }) {
const { slug } = params
const filePath = path.join(process.cwd(), 'content', 'blog', `${slug}.mdx`)
const source = await fs.readFile(filePath, 'utf8')
const { data: frontmatter, content } = matter(source)
const mdxSource = await serialize(content, {
parseFrontmatter: false,
scope: frontmatter,
})
return (
<article>
<header>
<h1>{frontmatter.title}</h1>
<div>
<time>{frontmatter.date}</time>
<span>·</span>
<span>{frontmatter.readTime} 分钟阅读</span>
</div>
<img src="{frontmatter.cover}" alt="{frontmatter.title}" />
</header>
<div>
<aside>
</aside>
<div>
</div>
</div>
</article>
)
}
export async function generateStaticParams() {
const files = await fs.readdir(path.join(process.cwd(), 'content', 'blog'))
return files
.filter(file => file.endsWith('.mdx'))
.map(file => ({ slug: file.replace('.mdx', '') }))
}
export default BlogPost
功能亮点:
– 直接读取文件,无需 API
– 支持 MDX(Markdown + React 组件)
– 自动生成目录
– SEO 友好
案例 3:实时数据仪表盘
场景:监控仪表盘需要实时更新数据,但要保持服务端渲染。
// app/dashboard/page.js
import db from '@/lib/db'
import { RealTimeChart } from '@/components/RealTimeChart'
async function DashboardPage() {
// 初始数据在服务端获取
const initialMetrics = await db.query(`
SELECT
DATE_TRUNC('hour', created_at) as time,
COUNT(*) as count
FROM events
WHERE created_at > NOW() - INTERVAL '24 hours'
GROUP BY time
ORDER BY time
`)
const stats = await db.query(`
SELECT
COUNT(*) as total_users,
COUNT(CASE WHEN active THEN 1 END) as active_users,
AVG(session_duration) as avg_session
FROM user_sessions
WHERE created_at > NOW() - INTERVAL '1 hour'
`)
return (
<div>
<h1>实时监控</h1>
<div>
</div>
{/* 客户端组件接管实时更新 */}
</div>
)
}
// 每 10 秒重新验证数据
export const revalidate = 10
export default DashboardPage
// components/RealTimeChart.js
'use client'
import { useEffect, useState } from 'react'
export function RealTimeChart({ initialData }) {
const [data, setData] = useState(initialData)
useEffect(() => {
const interval = setInterval(async () => {
const response = await fetch('/api/metrics/realtime')
const newData = await response.json()
setData(newData)
}, 5000) // 每 5 秒更新
return () => clearInterval(interval)
}, [])
return
}
性能优化建议
1. 数据库查询优化
// ❌ 不好:N+1 查询
async function BadPage() {
const users = await db.query('SELECT * FROM users')
return (
<div>
{users.map(async user => {
// 每个用户都查询一次!
const posts = await db.query('SELECT * FROM posts WHERE user_id = $1', [user.id])
return
})}
</div>
)
}
// ✅ 好:JOIN 查询
async function GoodPage() {
const users = await db.query(`
SELECT
u.*,
ARRAY_AGG(jsonb_build_object('id', p.id, 'title', p.title)) as posts
FROM users u
LEFT JOIN posts p ON u.id = p.user_id
GROUP BY u.id
`)
return (
<div>
{users.map(user => (
))}
</div>
)
}
2. 缓存策略
// lib/cache.js
const cache = new Map()
export function withCache(key, fn, ttl = 3600) {
if (cache.has(key)) {
const { value, expiry } = cache.get(key)
if (Date.now() db.query('SELECT * FROM products'),
3600 // 1 小时缓存
)
return
}
export const revalidate = 3600
export default ProductsPage
3. 流式渲染
// app/feed/page.js
import { Suspense } from 'react'
async function SlowComponent() {
await new Promise(resolve => setTimeout(resolve, 3000))
return <div>慢内容</div>
}
async function FastComponent() {
return <div>快内容</div>
}
function FeedPage() {
return (
<div>
<h1>流式渲染</h1>
{/* 立即显示 */}
{/* 延迟显示,不阻塞整体 */}
<Suspense fallback={}>
</div>
)
}
export default FeedPage
4. 代码分割
// app/charts/page.js
import dynamic from 'next/dynamic'
// 大型库延迟加载
const HeavyChart = dynamic(
() => import('@/components/HeavyChart'),
{
loading: () => <p>加载图表...</p>,
ssr: false, // 仅客户端
}
)
async function ChartsPage() {
const data = await db.query('SELECT * FROM analytics')
return (
<div>
<h1>数据分析</h1>
</div>
)
}
export default ChartsPage
故障排查指南
常见问题 FAQ
#### Q1: 服务端组件中使用客户端 API 报错?
问题:
Error: `window` is not defined
原因:服务端组件在服务器执行,无法访问 `window`、`document` 等浏览器 API。
解决方案:
// ❌ 错误
function ServerComponent() {
const width = window.innerWidth // 报错!
return <div>{width}</div>
}
// ✅ 正确:将客户端逻辑移到客户端组件
'use client'
function ClientComponent() {
const [width, setWidth] = useState(0)
useEffect(() => {
setWidth(window.innerWidth)
}, [])
return <div>{width}</div>
}
#### Q2: 数据库连接失败?
问题:
Error: Can't reach database server at localhost:5432
排查步骤:
1. 检查数据库连接字符串
echo $DATABASE_URL
# postgresql://user:password@localhost:5432/mydb
2. 测试连接
// lib/db.js
import { Pool } from 'pg'
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
})
// 测试连接
pool.query('SELECT NOW()', (err, res) => {
if (err) {
console.error('数据库连接失败:', err)
} else {
console.log('数据库连接成功:', res.rows)
}
})
export default pool
3. 检查防火墙
# 测试数据库端口
telnet localhost 5432
#### Q3: Hydration 错误?
问题:
Warning: Text content did not match. Server: "Hello" Client: "Hello World"
原因:服务端和客户端渲染内容不一致。
解决方案:
// ❌ 错误:使用随机数
function Component() {
const id = Math.random() // 服务端和客户端值不同!
return <div>{id}</div>
}
// ✅ 正确:使用 useEffect 仅在客户端生成
'use client'
function Component() {
const [id, setId] = useState(null)
useEffect(() => {
setId(Math.random())
}, [])
return <div>{id || '加载中...'}</div>
}
#### Q4: 组件不更新?
问题:修改代码后页面没有更新。
排查:
1. 清除 `.next` 缓存
rm -rf .next
npm run dev
2. 检查 `revalidate` 设置
// 禁用缓存
export const dynamic = 'force-dynamic'
// 或设置重新验证时间
export const revalidate = 10 // 秒
3. 检查开发服务器日志
npm run dev
# 查看终端输出的错误信息
#### Q5: fetch 请求失败?
问题:
TypeError: fetch failed
解决方案:
// ❌ 错误:使用相对路径
async function Page() {
const data = await fetch('/api/data') // 可能失败
return <div>{data}</div>
}
// ✅ 正确:使用绝对路径或直接查询
async function Page() {
// 方案 1:绝对路径
const data = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/data`)
// 方案 2:直接查询数据库
const data = await db.query('SELECT * FROM data')
return <div>{data}</div>
}
最佳实践总结
1. 架构原则
DO(推荐做法):
– ✅ 使用服务端组件进行数据获取
– ✅ 使用客户端组件处理交互
– ✅ 合理使用 Suspense 流式渲染
– ✅ 设置适当的缓存策略
– ✅ 使用 TypeScript 类型安全
– ✅ 错误边界处理异常
DON’T(避免做法):
– ❌ 在服务端组件使用浏览器 API
– ❌ 在客户端组件直接查数据库
– ❌ 过度使用 `use client`(增加包体积)
– ❌ 忽视错误处理
– ❌ 不设置缓存策略
– ❌ 同步等待慢查询
2. 性能清单
– [ ] 使用服务端组件减少客户端 JavaScript
– [ ] 实施流式渲染(Suspense)
– [ ] 设置适当的 `revalidate` 时间
– [ ] 使用 `generateStaticParams` 预渲染
– [ ] 优化数据库查询(避免 N+1)
– [ ] 实施缓存策略
– [ ] 代码分割大型库
– [ ] 监控首屏加载时间(LCP)
– [ ] 监控总阻塞时间(TBT)
– [ ] 监控累积布局偏移(CLS)
3. 迁移策略
从 Next.js 13 迁移:
# 1. 升级依赖
npm install next@14 react@latest react-dom@latest
# 2. 更新配置
# next.config.js
module.exports = {
experimental: {
serverComponents: true,
},
}
# 3. 逐步迁移页面
# - 从静态页面开始
# - 迁移数据展示页面
# - 最后迁移复杂交互页面
# 4. 测试
npm run build
npm run start
从 Pages Router 迁移:
// 旧的 pages/index.js
export default function Page({ data }) {
return <div>{data}</div>
}
export async function getServerSideProps() {
const data = await fetch('...')
return { props: { data } }
}
// 新的 app/page.js
async function Page() {
const data = await fetch('...') // 直接查询!
return <div>{data}</div>
}
4. 调试技巧
// 启用调试日志
export async function Page() {
console.log('服务端日志:执行中...')
const data = await db.query('...')
console.log('查询结果:', data)
return <div>{data}</div>
}
// 使用 React DevTools
// 1. 安装 React DevTools 浏览器扩展
// 2. 查看组件树
// 3. 检查 Props 和 State
// 性能监控
export async function Page() {
const start = Date.now()
const data = await db.query('...')
console.log(`查询耗时: ${Date.now() - start}ms`)
return <div>{data}</div>
}
5. 部署检查
# 构建生产版本
npm run build
# 检查构建输出
ls -lh .next/
# - server/ 服务端组件
# - static/ 静态页面
# - server-app/ 应用代码
# 测试生产版本
npm run start
# 环境变量检查
node -e "console.log(process.env.DATABASE_URL)"
# PM2 部署
pm2 start npm --name "my-app" -- start
pm2 logs my-app
pm2 monit
总结
Next.js 14 的服务端组件是一项革命性特性,通过将组件执行移至服务器,大幅减少了客户端 JavaScript 体积,提升了首屏加载性能,同时简化了开发流程。关键要点:
1. 性能优先:服务端组件减少 30-50% 客户端代码
2. 开发简化:直接访问数据库,无需 API 层
3. SEO 友好:完整的服务端渲染
4. 流式渲染:Suspense 支持渐进式加载
5. 混合架构:服务端和客户端组件协同工作
掌握服务端组件将帮助您构建更快、更现代的 Next.js 应用!
—
相关资源:
– [Next.js 官方文档](https://nextjs.org/docs)
– [React Server Components RFC](https://github.com/reactjs/rfcs/blob/main/text/0000-server-components.md)
– [Next.js 14 发布公告](https://nextjs.org/blog/next-14)