文档说明

本文档面向Web开发初学者,全程无晦涩术语、代码可直接复制运行。你将系统掌握Next.js的核心定位、解决的行业痛点、与传统开发模式的核心差异,从0搭建项目、吃透三大核心渲染模式、完成「调用第三方API+数据库增删改查」的全栈实战,最终掌握企业级最佳实践与适用场景,看完即可独立开发上线完整项目。


一、什么是Next.js?

Next.js 是由Vercel公司开发、Meta官方推荐的React全栈Web开发框架。

它把前端页面渲染、后端服务逻辑、路由系统、数据获取、性能优化、部署上线等全流程能力整合到一套代码中,彻底打破了「前端只管页面、后端只管接口」的传统壁垒,让你只用React语法,就能开发出高性能、SEO友好、安全可靠的全栈Web应用。

简单说:一套React代码,搞定前端+后端,不用再分开写前端项目和后端接口项目。


二、传统Web开发的核心痛点(Next.js的解决之道)

在Next.js普及之前,Web开发主要分为两种模式,均存在无法规避的核心痛点,这也是Next.js诞生的核心原因。

2.1 两种传统开发模式的致命痛点

传统开发模式核心特点无法解决的痛点
传统服务端渲染(PHP/JSP/Java模板)页面在服务端生成HTML返回给浏览器,前后端代码高度耦合1. 前后端强绑定,前端改页面需要后端配合,开发效率极低;
2. 页面跳转全量刷新,用户体验差;
3. 无法使用现代React/Vue前端生态,交互能力弱
前后端分离(React SPA + 独立后端API)前端单独写单页应用,通过fetch/axios调用后端接口,前后端完全分离1. 首屏白屏严重:需要先下载完整JS包,再渲染页面、请求数据,低端机/弱网体验极差;
2. SEO天生残疾:页面内容由JS动态渲染,搜索引擎爬虫无法抓取有效内容;
3. 开发成本高:一个简单的用户新增功能,需要前端写页面、后端写接口、双方联调、处理跨域/错误/loading,代码量翻倍;
4. 安全风险高:前端无法直接操作数据库,所有数据操作依赖接口,接口多了极易出现权限遗漏、数据越权问题;
5. 运维复杂:前端部署CDN、后端部署服务器,需要配置跨域、HTTPS、缓存,出问题需要两端排查

2.2 Next.js 如何一次性解决所有痛点?

针对以上痛点,Next.js给出了一站式解决方案,核心能力如下:

  1. 多渲染模式自由切换:同时支持SSR(服务端渲染)、SSG(静态生成)、ISR(增量静态更新)、CSR(客户端渲染),既解决了SPA的白屏&SEO问题,又保留了现代前端的丝滑交互体验;

  2. Server Actions 全栈能力:无需单独写API接口,直接在React组件中编写服务端函数,即可安全操作数据库、调用私密接口,彻底告别「接口联调地狱」;

  3. 文件式路由系统:文件夹结构=页面路由,无需手动配置路由规则,零配置实现嵌套路由、动态路由、权限路由;

  4. 内置全自动性能优化:图片自动压缩/懒加载、代码自动分割、路由预加载、字体优化,新手也能写出高性能页面;

  5. 服务端代码天然隔离:服务端逻辑永远不会发送到浏览器,数据库密码、API密钥等敏感信息100%安全;

  6. 一体化部署:一套代码一键部署,无需分开维护前后端服务,彻底解决跨域、版本不同步问题。


三、Next.js 与传统Web开发的核心优势对比

对比维度传统前后端分离传统PHP/JSP服务端渲染Next.js 全栈框架
首屏加载速度慢,白屏时间长较快,跳转全量刷新极快,服务端返回完整HTML,跳转无刷新
SEO友好度差,需额外做预渲染改造良好,内容直接返回优秀,天然支持所有搜索引擎抓取
开发效率低,需写接口、联调、处理跨域低,前后端耦合,改造成本高极高,一套代码搞定前后端,零接口联调
数据安全性依赖接口权限校验,易出现漏洞较好,逻辑在服务端优秀,服务端代码物理隔离,内置CSRF防护
交互体验优秀,无刷新跳转差,页面全量刷新优秀,内置路由预加载,原生级交互体验
性能优化门槛高,需手动配置代码分割、图片优化等低,优化能力有限极低,框架内置全自动优化,开箱即用
部署运维成本高,前后端分开部署、配置中,需配置服务端环境极低,一键部署,一体化运维
无JS兼容性完全不可用,页面白屏可用,交互能力弱可用,内容正常展示,表单可正常提交

四、快速入门:5分钟从0搭建第一个Next.js项目

4.1 环境准备

仅需安装 Node.js 18.17及以上版本(官网下载LTS版本,一路默认安装即可),安装完成后在终端执行以下命令,能输出版本号即安装成功:

node -v

4.2 创建项目

打开终端,进入你想存放项目的文件夹,执行以下创建命令:

npx create-next-app@latest my-first-next-app

执行后会出现配置选项,新手一路按回车选择默认配置即可,默认配置包含:TypeScript、ESLint、Tailwind CSS、App Router(最新路由系统)。

4.3 启动项目

创建完成后,依次执行以下命令进入项目、启动开发服务器:

# 进入项目文件夹
cd my-first-next-app
# 启动开发服务器
npm run dev

启动成功后,打开浏览器访问 http://localhost:3000,看到Next.js欢迎页面,即项目搭建成功!

4.4 新手必懂的核心项目结构

my-first-next-app/
├── app/           【核心】路由文件夹,文件结构=页面路由
│   ├── page.tsx   首页,对应访问路径 /
│   ├── layout.tsx 全局布局文件,所有页面共用
│   └── about/     新建about文件夹,对应路由 /about
│       └── page.tsx 关于页面,对应访问路径 /about
├── public/        静态资源文件夹,存放图片、图标等
├── lib/           工具类文件夹,存放数据库连接、工具函数等(需手动创建)
└── package.json   项目依赖配置文件

核心规则:app 文件夹下,每一个 page.tsx 文件,都会自动生成一个对应路径的页面,无需手动配置路由,路由分为三类:

  1. 基础规则: app/ 文件夹内部的层级结构 = 网址 URL只有创建了 page.tsx,这个路径才能被访问

  2. 固定路由: 文件夹名不带 [] = 写死的固定网址

    app/about/page.tsx      →  访问 /about
    app/blog/page.tsx       →  访问 /blog
    
  3. 动态路由: 文件夹名带 [] = 可变参数的动态网址

    app/blog/[slug]/page.tsx  →  访问 /blog/1、/blog/abc、/blog/任意值
    

代码目录和路由关系:

你的项目目录               →  浏览器访问地址
└── app/
    ├── page.tsx          →  localhost:3000/           (首页)
    ├── about/
    │   └── page.tsx      →  localhost:3000/about       (固定路由)
    └── blog/
        ├── page.tsx      →  localhost:3000/blog        (固定路由)
        └── [id]/
            └── page.tsx  →  localhost:3000/blog/123    (动态路由)

五、Next.js 四大核心渲染模式详解(含代码示例)

渲染模式是Next.js的核心灵魂,它决定了页面何时生成、数据何时获取,直接影响页面性能、SEO和服务器压力。Next.js App Router 原生支持四大核心渲染模式(SSR、SSG、ISR、CSR),无需复杂配置,几行代码即可切换,所有示例均基于公开的文章API,可直接复制运行。

5.1 SSG(Static Site Generation 静态站点生成)

核心定义

SSG是Next.js默认的渲染模式,也是性能最优的模式。它会在项目构建阶段(执行npm run build时),提前执行数据获取、渲染生成完整的静态HTML文件,部署后所有用户访问都直接返回这个预先生成的静态文件,无需服务端重复执行代码、查询接口/数据库。

特点:

  • build 时一次性生成 HTML
  • 部署后内容不会变
  • 最快、最利于 SEO

适用场景

不常更新的静态内容页面:企业官网、个人博客、帮助文档、营销落地页、静态新闻列表。

核心优势

  • 访问速度极快:静态文件可直接托管在CDN,用户打开秒开;

  • 零服务器运行压力:无需每次请求执行服务端逻辑,高并发无压力;

  • 极致SEO友好:完整HTML内容直接被搜索引擎抓取;

  • 稳定性极强:无服务端代码执行,不会出现接口超时等运行时错误。

完整代码示例

新建文件 app/ssg-posts/page.tsx,写入以下代码:

// app/ssg-posts/page.tsx 对应访问路径 /ssg-posts
// 无任何强制动态配置,Next.js默认使用SSG静态生成
interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

// 构建时执行数据获取,生成静态页面
async function getStaticPosts(): Promise<Post[]> {
  // fetch默认开启强制缓存,构建时拉取数据后永久缓存
  const res = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=10');
  if (!res.ok) throw new Error('数据获取失败');
  return res.json();
}

// 页面组件
export default async function SSGPostsPage() {
  // 构建时获取数据,前端访问直接返回预渲染的HTML
  const posts = await getStaticPosts();

  return (
    <div className="max-w-3xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-8">SSG静态生成文章列表</h1>
      <p className="mb-6 text-gray-500">本页面在构建时预渲染,所有用户访问均返回静态HTML</p>
      <div className="space-y-4">
        {posts.map((post) => (
          <div key={post.id} className="border rounded-lg p-4 shadow-sm">
            <h2 className="text-xl font-semibold mb-2">{post.title}</h2>
            <p className="text-gray-600">{post.body}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

验证方式

执行 npm run build 打包项目,在打包日志中,该页面会标记为 ○ (Static),即代表SSG静态生成成功。


5.2 SSR(Server-Side Rendering 服务端渲染)

核心定义

SSR即动态服务端渲染,用户每次发起页面请求时,服务端都会实时执行数据获取、渲染完整的HTML页面,再返回给浏览器。每次请求都会重新执行代码、拉取最新数据。

特点:

  • 每次访问都重新生成 HTML
  • 数据永远最新
  • 性能比 SSG/ISR 差

适用场景

强实时性、强个性化的动态页面:实时数据仪表盘、个人中心、库存实时变动的商品详情页、需要实时权限校验的页面。

核心优势

  • 数据永远最新:每次请求都拉取实时数据,无缓存延迟;

  • SEO友好:完整HTML内容直接返回,搜索引擎可正常抓取;

  • 个性化能力强:可根据用户请求信息(Cookie、登录态)返回个性化内容;

  • 首屏性能优秀:无需等待客户端JS下载执行,直接返回渲染好的页面。

完整代码示例

新建文件 app/ssr-posts/page.tsx,写入以下代码:

// app/ssr-posts/page.tsx 对应访问路径 /ssr-posts
// 强制动态渲染,每次请求都重新执行服务端逻辑
interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

// 每次用户请求页面时,都会实时执行该函数拉取最新数据
async function getDynamicPosts(): Promise<Post[]> {
  // cache: 'no-store' 强制不缓存,每次请求都重新调用接口
  const res = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=10', {
    cache: 'no-store'
  });
  if (!res.ok) throw new Error('数据获取失败');
  return res.json();
}

// 页面组件
export default async function SSRPostsPage() {
  // 每次请求都实时获取最新数据
  const posts = await getDynamicPosts();
  // 可获取当前请求时间,验证每次刷新都会更新
  const requestTime = new Date().toLocaleString();

  return (
    <div className="max-w-3xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-4">SSR服务端渲染文章列表</h1>
      <p className="mb-6 text-gray-500">本页面每次刷新都会重新渲染,当前请求时间:{requestTime}</p>
      <div className="space-y-4">
        {posts.map((post) => (
          <div key={post.id} className="border rounded-lg p-4 shadow-sm">
            <h2 className="text-xl font-semibold mb-2">{post.title}</h2>
            <p className="text-gray-600">{post.body}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

验证方式

  1. 执行 npm run build 打包项目,在打包日志中,该页面会标记为 λ (Dynamic),即代表SSR动态渲染;

  2. 启动生产服务 npm run start,访问页面后多次刷新,可看到页面上的请求时间每次都会更新,验证每次请求都重新渲染。


5.3 ISR(Incremental Static Regeneration 增量静态再生成)

核心定义

ISR是Next.js的王牌功能,完美结合了SSG的极致性能和SSR的实时性优势。它在构建时预生成静态页面,部署后可按照你设定的时间间隔,在后台自动重新拉取数据、渲染更新静态页面,无需重新构建、重新部署项目。

简单说:静态页面的访问速度,同时支持数据自动定期更新。

特点:

  • 先 SSG,定时自动刷新
  • 访问快 + 数据能更新
  • 用 revalidate 控制刷新时间

适用场景

需要定期更新、但无需实时的页面:新闻资讯列表、电商商品列表、博客文章、论坛帖子列表,访问量高但更新频率不高的内容。

核心优势

  • 兼顾速度与新鲜度:既有SSG的静态访问速度,又能定期更新数据;

  • 极低的服务器压力:无论多少用户访问,仅在设定的间隔内执行一次数据更新;

  • 无需重新部署:内容更新无需重新打包构建,后台自动完成;

  • 容错能力强:即使更新时接口出错,仍会返回之前的静态页面,不会影响用户访问。

完整代码示例

新建文件 app/isr-posts/page.tsx,写入以下代码:

// app/isr-posts/page.tsx 对应访问路径 /isr-posts
// 增量静态再生成,设置60秒重新验证更新一次数据
interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

// 设定页面缓存有效期,单位:秒
// 60秒内的所有访问,都返回缓存的静态页面;60秒后首次访问,后台自动更新页面
export const revalidate = 60;

// 构建时预执行,后续每60秒自动重新执行更新数据
async function getISRPosts(): Promise<Post[]> {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=10');
  if (!res.ok) throw new Error('数据获取失败');
  return res.json();
}

// 页面组件
export default async function ISRPostsPage() {
  const posts = await getISRPosts();
  // 页面生成时间,验证缓存更新
  const generateTime = new Date().toLocaleString();

  return (
    <div className="max-w-3xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-4">ISR增量静态更新文章列表</h1>
      <p className="mb-6 text-gray-500">本页面每60秒自动更新一次,当前页面生成时间:{generateTime}</p>
      <div className="space-y-4">
        {posts.map((post) => (
          <div key={post.id} className="border rounded-lg p-4 shadow-sm">
            <h2 className="text-xl font-semibold mb-2">{post.title}</h2>
            <p className="text-gray-600">{post.body}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

验证方式

  1. 执行 npm run build 打包项目,在打包日志中,该页面会标记为 ● (ISR),即代表增量静态更新配置成功;

  2. 启动生产服务 npm run start,首次访问页面记录生成时间,后续60秒内刷新,时间不会变化(返回缓存静态页);60秒后再次刷新,页面会更新为最新的生成时间,验证后台自动更新生效。


5.4 CSR(Client-Side Rendering 客户端渲染)

核心定义

CSR即客户端渲染,是传统React SPA的核心渲染模式。服务端仅返回一个空的HTML模板(包含JS引用),页面渲染、数据获取等逻辑全部在浏览器端(客户端)执行,通过JS动态生成页面内容并插入到HTML中,完成页面展示。

简单说:服务端只给“空壳”,浏览器自己加载JS、获取数据、渲染页面,也是Next.js中需手动开启的渲染模式(标记'use client')。

特点:

  • 纯前端渲染,首屏无内容
  • 数据在浏览器里请求
  • 不利于 SEO
  • 无缓存

适用场景

强交互、无SEO需求、数据频繁变动的页面:后台管理系统、用户个人中心(非公开内容)、在线编辑器、社交应用动态 feed、游戏类Web应用。

核心优势

  • 交互体验极致流畅:页面渲染和数据更新都在客户端完成,无需请求服务端,跳转、操作无延迟;

  • 减轻服务端压力:服务端仅返回静态模板,无需执行渲染和数据查询逻辑,高并发场景下优势明显;

  • 动态交互能力强:支持复杂的用户交互(如拖拽、实时输入反馈、弹窗联动),适配需要大量JS交互的场景;

  • 开发灵活:完全沿用传统React开发模式,熟悉React的开发者可快速上手,无需额外学习服务端渲染逻辑。

完整代码示例

新建文件 app/csr-posts/page.tsx,写入以下代码(明确标记客户端渲染,适配复杂交互场景):

// app/csr-posts/page.tsx 对应访问路径 /csr-posts
'use client'; // 标记为客户端组件,强制开启CSR客户端渲染

import { useState, useEffect } from 'react';

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

export default function CSRPostsPage() {
  // 客户端维护状态,用于交互和数据展示
  const [posts, setPosts] = useState<Post[]>([]);
  const [loading, setLoading] = useState(true);
  const [searchKey, setSearchKey] = useState(''); // 客户端交互状态(搜索)

  // 客户端数据获取,在浏览器端执行
  const fetchPosts = async () => {
    setLoading(true);
    try {
      // 客户端请求API,可根据交互状态(如搜索关键词)动态调整请求参数
      const res = await fetch(`https://jsonplaceholder.typicode.com/posts?q=${searchKey}`);
      if (!res.ok) throw new Error('数据获取失败');
      const data = await res.json();
      setPosts(data.slice(0, 10)); // 截取前10条数据
    } catch (err) {
      console.error('客户端请求失败', err);
    } finally {
      setLoading(false);
    }
  };

  // 组件挂载时获取初始数据,搜索关键词变化时重新获取数据
  useEffect(() => {
    fetchPosts();
  }, [searchKey]);

  return (
    <div className="max-w-3xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-8">CSR客户端渲染文章列表</h1>
      <p className="mb-6 text-gray-500">本页面在浏览器端渲染,数据获取和页面更新均在客户端完成</p>

      // 客户端交互组件(搜索框),体现CSR交互优势
      <div className="mb-6">
        <input
          type="text"
          placeholder="输入关键词搜索文章..."
          value={searchKey}
          onChange={(e) => setSearchKey(e.target.value)}
          className="w-full px-4 py-2 border rounded-lg shadow-sm"
        />
      </div>

      {loading ? (
        <div className="p-6 text-center">加载中...</div>
      ) : (
        <div className="space-y-4">
          {posts.map((post) => (
            <div key={post.id} className="border rounded-lg p-4 shadow-sm">
              <h2 className="text-xl font-semibold mb-2">{post.title}</h2>
              <p className="text-gray-600">{post.body.substring(0, 100)}...</p>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

验证方式

  1. 执行 npm run dev 启动开发服务,访问 http://localhost:3000/csr-posts,可看到页面先显示“加载中”,随后渲染内容(验证客户端渲染流程);

  2. 打开浏览器“开发者工具”,切换到「Network」面板,刷新页面,可看到服务端仅返回 csr-posts 相关的HTML和JS文件,数据请求(fetch)是在客户端发起的;

  3. 在搜索框输入关键词(如“test”),页面会实时重新请求数据并更新,无需刷新页面,验证客户端交互与动态渲染能力。


六、核心实战:2个必学示例(调用第三方API + 数据库增删改查)

以下示例代码均可直接复制运行,全程基于Next.js最新的App Router和Server Components,符合企业级开发规范。

示例1:调用第三方API(2种常用方式,新手必懂)

我们以公开的「文章数据API」为例,地址:https://jsonplaceholder.typicode.com/posts,无需申请密钥,可直接调用。

Next.js中调用API分为服务端调用和客户端调用,优先推荐服务端调用,性能更好、SEO更友好、无跨域问题。

方式1:服务端组件调用(推荐,90%场景首选)

Next.js中,没有加 'use client' 标记的组件,默认都是服务端组件,代码只在服务端运行,可直接用 async/await 调用API,无需useEffect、无需处理loading状态。

新建文件 app/posts/page.tsx,写入以下代码:

// app/posts/page.tsx 对应访问路径 /posts
// 无'use client',默认是服务端组件,代码只在服务端运行

// 定义接口返回数据类型
interface Post {
  id: number;
  title: string;
  body: string;
}

// 服务端调用第三方API
async function getPosts(): Promise<Post[]> {
  // 调用第三方API,Next.js默认会缓存结果,避免重复请求
  const res = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=10');
  if (!res.ok) throw new Error('接口请求失败');
  return res.json();
}

// 页面组件,直接async/await获取数据
export default async function PostsPage() {
  // 直接在组件中获取数据,服务端执行,前端看不到接口调用逻辑
  const posts = await getPosts();

  return (
    <div className="max-w-3xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-8">第三方API文章列表</h1>
      <div className="space-y-4">
        {posts.map((post) => (
          <div key={post.id} className="border rounded-lg p-4 shadow-sm">
            <h2 className="text-xl font-semibold mb-2">{post.title}</h2>
            <p className="text-gray-600">{post.body}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

保存后,访问 http://localhost:3000/posts,即可看到渲染好的文章列表。

核心优势:

  • 页面打开直接显示内容,无白屏、无loading等待;
  • 搜索引擎直接抓取到完整内容,SEO拉满;
  • 接口调用在服务端完成,前端看不到接口地址,无跨域问题;
  • Next.js默认缓存接口结果,重复访问不会重复调用第三方API。

方式2:客户端组件调用(仅用于需要实时交互的场景)

如果你的页面需要按钮点击、实时输入等用户交互,需要使用客户端组件,加 'use client' 标记,用法和传统React一致。

新建文件 app/client-posts/page.tsx,写入以下代码:

// app/client-posts/page.tsx 对应访问路径 /client-posts
'use client'; // 标记为客户端组件,代码会发送到浏览器

import { useEffect, useState } from 'react';

interface Post {
  id: number;
  title: string;
  body: string;
}

export default function ClientPostsPage() {
  const [posts, setPosts] = useState<Post[]>([]);
  const [loading, setLoading] = useState(true);

  // 客户端调用API,和传统React用法一致
  useEffect(() => {
    const fetchPosts = async () => {
      try {
        const res = await fetch('https://jsonplaceholder.typicode.com/posts?_limit=10');
        const data = await res.json();
        setPosts(data);
      } catch (err) {
        console.error('请求失败', err);
      } finally {
        setLoading(false);
      }
    };
    fetchPosts();
  }, []);

  if (loading) return <div className="p-6">加载中...</div>;

  return (
    <div className="max-w-3xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-8">客户端调用API文章列表</h1>
      <div className="space-y-4">
        {posts.map((post) => (
          <div key={post.id} className="border rounded-lg p-4 shadow-sm">
            <h2 className="text-xl font-semibold mb-2">{post.title}</h2>
            <p className="text-gray-600">{post.body}</p>
          </div>
        ))}
      </div>
    </div>
  );
}

示例2:连接数据库,实现完整增删改查(CRUD)

我们使用SQLite作为数据库,无需安装任何数据库服务、无需配置账号密码,开箱即用,新手零门槛。搭配Next.js的Server Actions,无需写任何API接口,即可安全实现数据库增删改查。

步骤1:安装依赖

在项目终端执行以下命令,安装数据库依赖:

npm install better-sqlite3
# 类型声明,TypeScript项目需要
npm install -D @types/better-sqlite3

步骤2:创建数据库连接工具类

新建 lib/db.ts 文件,写入以下代码,实现数据库连接和表初始化:

// lib/db.ts
import Database from 'better-sqlite3';

// 连接数据库,自动创建db.sqlite3文件,无需手动创建
const db = new Database('db.sqlite3');

// 初始化用户表,第一次运行自动创建,后续运行不会重复创建
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT NOT NULL UNIQUE,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

export default db;

步骤3:创建Server Actions,实现增删改查逻辑

新建 app/users/actions.ts 文件,写入以下代码,所有函数都标记为服务端操作,代码只在服务端运行,绝对不会暴露给前端:

// app/users/actions.ts
'use server'; // 标记整个文件的函数都是Server Actions,只在服务端运行

import db from '@/lib/db';
import { revalidatePath } from 'next/cache';

// 1. 新增用户
export async function addUser(formData: FormData) {
  // 从表单中获取数据
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;

  if (!name || !email) throw new Error('姓名和邮箱不能为空');

  try {
    // 执行数据库插入操作
    db.prepare('INSERT INTO users (name, email) VALUES (?, ?)').run(name, email);
    // 刷新页面数据,让用户看到最新的列表
    revalidatePath('/users');
    return { success: true, message: '用户添加成功' };
  } catch (err) {
    console.error('添加用户失败', err);
    return { success: false, message: '邮箱已存在,添加失败' };
  }
}

// 2. 删除用户
export async function deleteUser(id: number) {
  try {
    db.prepare('DELETE FROM users WHERE id = ?').run(id);
    revalidatePath('/users');
    return { success: true };
  } catch (err) {
    console.error('删除用户失败', err);
    return { success: false, message: '删除失败' };
  }
}

// 3. 修改用户
export async function updateUser(formData: FormData) {
  const id = Number(formData.get('id'));
  const name = formData.get('name') as string;

  if (!id || !name) throw new Error('参数错误');

  try {
    db.prepare('UPDATE users SET name = ? WHERE id = ?').run(name, id);
    revalidatePath('/users');
    return { success: true, message: '修改成功' };
  } catch (err) {
    console.error('修改用户失败', err);
    return { success: false, message: '修改失败' };
  }
}

// 4. 查询用户列表
export function getUsers() {
  return db.prepare('SELECT * FROM users ORDER BY create_time DESC').all();
}

步骤4:创建页面,实现完整的用户管理功能

新建 app/users/page.tsx 文件,写入以下代码,实现表单提交、用户列表展示、修改和删除功能:

// app/users/page.tsx 对应访问路径 /users
import { addUser, deleteUser, getUsers, updateUser } from './actions';

export default function UsersPage() {
  // 服务端直接查询数据库,前端看不到任何数据库逻辑
  const users = getUsers();

  return (
    <div className="max-w-4xl mx-auto p-6">
      <h1 className="text-3xl font-bold mb-8">用户管理系统(数据库增删改查)</h1>

      {/* 新增用户表单,直接绑定Server Action,无需写onSubmit、无需写fetch */}
      <form action={addUser} className="flex gap-3 mb-10 p-4 border rounded-lg shadow-sm">
        <input
          type="text"
          name="name"
          placeholder="请输入姓名"
          className="flex-1 px-3 py-2 border rounded"
          required
        />
        <input
          type="email"
          name="email"
          placeholder="请输入邮箱"
          className="flex-1 px-3 py-2 border rounded"
          required
        />
        <button
          type="submit"
          className="px-6 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
        >
          添加用户
        </button>
      </form>

      {/* 用户列表 */}
      <div className="border rounded-lg overflow-hidden">
        <table className="w-full">
          <thead className="bg-gray-50 border-b">
            <tr>
              <th className="px-4 py-3 text-left">ID</th>
              <th className="px-4 py-3 text-left">姓名</th>
              <th className="px-4 py-3 text-left">邮箱</th>
              <th className="px-4 py-3 text-left">创建时间</th>
              <th className="px-4 py-3 text-center">操作</th>
            </tr>
          </thead>
          <tbody className="divide-y">
            {users.length === 0 ? (
              <tr>
                <td colSpan={5} className="px-4 py-8 text-center text-gray-500">
                  暂无用户数据,请添加用户
                </td>
              </tr>
            ) : (
              users.map((user: any) => (
                <tr key={user.id}>
                  <td className="px-4 py-3">{user.id}</td>
                  <td className="px-4 py-3">{user.name}</td>
                  <td className="px-4 py-3">{user.email}</td>
                  <td className="px-4 py-3">{user.create_time}</td>
                  <td className="px-4 py-3 flex justify-center gap-2">
                    {/* 修改用户表单 */}
                    <form action={updateUser} className="inline">
                      <input type="hidden" name="id" value={user.id} />
                      <input
                        type="text"
                        name="name"
                        placeholder="新姓名"
                        className="w-24 px-2 py-1 border rounded"
                        required
                      />
                      <button
                        type="submit"
                        className="ml-1 px-3 py-1 bg-green-500 text-white rounded hover:bg-green-600"
                      >
                        修改
                      </button>
                    </form>

                    {/* 删除用户表单 */}
                    <form action={deleteUser.bind(null, user.id)} className="inline">
                      <button
                        type="submit"
                        className="px-3 py-1 bg-red-500 text-white rounded hover:bg-red-600"
                      >
                        删除
                      </button>
                    </form>
                  </td>
                </tr>
              ))
            )}
          </tbody>
        </table>
      </div>
    </div>
  );
}

步骤5:运行效果

保存所有代码后,访问 http://localhost:3000/users,你即可实现:

  • 表单提交添加用户,直接写入数据库;
  • 实时展示数据库中的用户列表;
  • 一键修改用户姓名,更新数据库;
  • 一键删除用户,同步数据库;
  • 所有操作无刷新、无需写任何API接口、数据库逻辑100%安全,不会暴露给前端。

七、Next.js 企业级开发最佳实践(新手照做不踩坑)

7.1 渲染模式选择最佳实践

  1. 能静态就静态:官网、博客、文档等不常更新的页面,优先使用SSG静态生成,零服务器压力、访问速度最快;
  2. 动态内容加缓存:商品列表、新闻等需要定期更新的页面,使用ISR增量静态更新,设置 revalidate = 60(缓存60秒),既保证数据新鲜度,又避免频繁查询数据库;
  3. 仅实时场景用纯SSR:只有后台实时数据、个人中心等强个性化、强实时性的页面,才使用 cache: 'no-store' 强制不缓存,避免滥用导致服务器压力过大;
  4. 客户端组件最小化:只有需要用户交互(按钮点击、输入框、状态管理)的组件,才加 'use client' 标记,其余全部用服务端组件,保证性能和安全。

7.2 安全开发最佳实践

  1. 永远不要在客户端组件中写数据库连接、密钥等敏感信息,所有敏感操作必须放在Server Actions或服务端组件中;
  2. 环境变量规范:只有需要暴露给前端的变量,才以 NEXT_PUBLIC_ 开头,数据库密码、API密钥等敏感变量,绝对不能加此前缀;
  3. Server Actions 必须做参数校验:所有用户提交的数据,必须做格式校验、权限校验,不能直接写入数据库;
  4. 禁止在客户端组件中内联Server Actions,客户端组件必须导入单独文件的Server Actions,避免代码泄露。

7.3 性能优化最佳实践

  1. 使用内置的Image组件:所有图片都用 next/image,自动实现压缩、懒加载、自适应,避免图片导致的性能问题;
  2. 使用内置的Font组件:用 next/font 加载字体,避免字体闪烁、加载慢的问题;
  3. 路由预加载:用 next/link 做页面跳转,Next.js会自动预加载目标页面,实现秒开跳转;
  4. 避免大体积客户端组件:大的交互组件,使用动态导入 dynamic(() => import('./xxx')),实现按需加载,减少首屏JS体积。

7.4 部署最佳实践

  1. 优先选择Vercel部署:Next.js官方出品,一键部署、零配置、自动扩容,免费额度足够个人项目和小型企业项目使用;
  2. 自有服务器部署:可使用Docker打包部署,或执行 npm run build 打包后,用 npm run start 启动生产服务;
  3. 生产环境必须关闭开发模式,避免源码泄露和性能问题。

八、Next.js 适用场景 & 不适用场景

8.1 强烈推荐使用的场景

  1. 企业官网、品牌官网、营销落地页:SEO友好、首屏秒开、部署简单,完美匹配需求;
  2. 博客、文档站、内容门户、新闻站点:SSG+ISR组合,既保证访问速度,又能轻松更新内容;
  3. 电子商务平台、商城站点:SSR+ISR兼顾SEO和实时价格/库存更新,Server Actions安全处理订单逻辑;
  4. SaaS应用、后台管理系统、仪表盘:全栈一体化开发,一套代码搞定页面和后端逻辑,开发效率翻倍;
  5. AI应用、工具类网站:服务端安全调用AI API,避免密钥泄露,同时保证前端交互体验;
  6. 移动端优先的Web应用、PWA:内置性能优化,弱网环境体验远超传统SPA。

8.2 不推荐使用的场景

  1. 纯静态无动态内容的单页:比如只有1-2个页面的纯静态介绍页,可选择更轻量的Astro、VitePress;
  2. 已有成熟超大型微服务后端体系:不建议用Next.js替代后端,可作为前端渲染层,调用现有微服务接口;
  3. 非React技术栈项目:Next.js基于React,Vue/Angular技术栈建议选择对应框架(Nuxt、Analog)。

九、总结

核心总结

Next.js 彻底重构了现代Web开发的流程,它不是简单的React框架,而是一套完整的全栈开发解决方案:

  • 它解决了传统前后端分离的SEO、首屏性能、开发效率痛点;
  • 它保留了现代前端的丝滑交互体验,同时补齐了服务端能力;
  • 它让前端开发者无需学习额外的后端语言,只用React语法,就能开发完整的全栈应用;
  • 它的企业级生态和性能优化能力,让新手也能写出符合生产标准的Web项目。