2026 我的 Next.js 搭建之路（1）：初始化项目

前言

作为一名长期深耕于外包公司的前端工程师，我大部分的项目都是使用 Vue2；此前学习的 Vue3 与 React，却始终没有机会在实际项目中落地实践。为了避免陷入颓废、被行业淘汰的困境，我计划着手搭建个人后台管理项目，全程记录使用 Next.js 的搭建流程，同时结合官方文档与 AI 工具，一步步完成项目落地，既巩固技术，也给自己的成长留下印记。

0 开发环境及依赖版本

开发环境

我这边开发环境选的是Node.js + pnpm组合。版本管理工具用的是 Volta，它最方便的地方就是能给不同项目配置不同的Node版本，不用来回切换麻烦。
具体用法很简单，常用命令贴在这：

# 将 Node.js 安装为默认版本，安装最新的 LTS（长期支持）版本的 Node.js。
volta install node

# 安装特定版本
volta install node@16
volta install node@16.14.2

# 特定的 Node.js 版本固定到您的项目
volta pin node@16.14.2

pnpm 的话，直接用 npm install -g pnpm 命令安装就行。

我现在用的 Node.js和 pnpm都是最新版本，做技术嘛，就得追着最新的来，后续用到的其他技术栈也会保持最新，同时兼顾好兼容性，避免出现版本不匹配的问题。

可以使用 node -v、pnpm -v 查看版本号。

因为项目是使用 Next 官方脚手架创建项目，默认给你配置好了最新的、可兼容的版本，其他的依赖直接上新版！咱使用的版本号如下：

依赖	版本	描述
next	16.1.5	Next.js 框架
react	19.2.3	React 核心
react-dom	19.2.3	React DOM 渲染
typescript	^5	静态类型检查
eslint	^9	代码检查
eslint-config-next	16.1.5	Next.js ESLint 规则
tailwindcss	^4	原子化 CSS 框架
@tailwindcss/postcss	^4	Tailwind CSS 编译

1. 初始化项目

1.1 创建项目

这边我使用的 Next.js 官方推荐的 create-next-app

npx create-next-app@latest

安装时，你将看到以下提示

? What is your project named? » my-app # 项目名称
? Would you like to use the recommended Next.js defaults? » - Use arrow-keys. Return to submit. # 推荐的Next.js默认值吗，
>   Yes, use recommended defaults - TypeScript, ESLint, Tailwind CSS, App Router # 是的，使用推荐的默认值-TypeScript、ESLint、Tailwind CSS、App Router
    No, reuse previous settings # 否，重复使用以前的设置
    No, customize settings # 否，自定义设置，我选这个
? Would you like to use TypeScript? » No / Yes # 你想使用TypeScript吗？ Yes
? Which linter would you like to use? » - Use arrow-keys. Return to submit.# 你想选择哪种代码检查工具
>   ESLint # 选择主流
    Biome 
    None
? Would you like to use React Compiler?  # 您想使用React编译器吗？
  » No / Yes # Yes
? Would you like to use Tailwind CSS? # 您想使用Tailwind CSS 吗
  » No / Yes # Yes
? Would you like your code inside a `src/` directory? # 你想把代码放在`src/`目录中吗
  » No / Yes # Yes
? Would you like to use App Router? (recommended) 您想使用App Router吗？
  » No / Yes # Yes
? Would you like to customize the import alias (`@/*` by default)? # 是否要自定义导入别名（默认为“@/*”）
  » No / Yes # No

1.2 安装依赖

使用 VScode 打开前面创建的项目 my-app,打开终端，输入 pnpm install 安装项目所需依赖。

1.3 启动项目

查看 package.json 配置文件

{
  ...
  "scripts": {
    "dev": "next dev", // 启动开发环境服务器
    "build": "next build", // 为生产环境构建 / 打包项目
    "start": "next start", // 启动生产环境服务器
    "lint": "eslint" // 运行代码检查工具
  },
  ...
}

启动项目，测试是否运行成功：

  pnpm dev

项目正常启动后，在浏览器中访问http://localhost:3000/

若页面能正常显示，且控制台不报任何异常，则项目创建启动成功。

2. 调整项目结构

2.1 项目文件 / 文件夹作用全解析

my-app/
├─ .next/ # Next.js 开发 / 打包时自动生成的临时缓存目录
├─ node_modules # 项目所有第三方依赖包的存放目录
├─ public/ # 静态资源（图片、favicon）
├─ src/
│  ├─ app/ # App Router 的核心路由目录
│  │  ├─ layout.tsx
│  │  ├─ page.tsx
│  ├─ components/ # 可复用组件（尽量小、可组合）
│  ├─ hooks/ # 自定义 hooks（useAuth, useToast）
│  ├─ lib/ # 数据客户端、工具函数（prisma client, supabase client）
│  ├─ styles/ # globals, tailwind css entry
│  ├─ types/ # 全局类型声明
│  └─ utils/ # 小工具
├─ .env.local # 本地环境变量（不要提交）
├─ next.config.js # Next.js 项目的全局配置文件
├─ postcss.config.js # PostCSS 工具的配置文件
├─ eslint.config.mjs # ESLint 代码检查工具的配置文件
├─ tsconfig.json # TypeScript 配置文件
├─ package.json # 项目核心配置文件
└─ README.md # 项目核心配置文件

2.2 创建测试页面

App Router 是文件系统路由，即「文件 / 文件夹的路径 = 页面的 URL 路径」。我们来创建一个 /test 测试页面：

在 src/app 目录下，新建一个名为 test 的文件夹。
test 文件夹里，新建一个名为 page.tsx 的文件（这是 App Router 中 “页面文件” 的固定命名）。
在 page.tsx 中写入测试代码：

// src/app/test/page.tsx
export default function TestPage() {
  return (
    <div style={{ padding: '2rem' }}>
      <h1>这是一个测试页面</h1>
      <p>访问路径：/test</p>
    </div>
  );
}

2.3 配置更多路由

如果你想快速体验多路由，还可以创建：

首页：src/app/page.tsx 就是默认的首页（访问路径 /），可以修改这个文件来定制首页内容。
嵌套路由：比如创建 src/app/blog/[id]/page.tsx，就能实现动态路由 /blog/123（[id] 是动态参数）。
全局布局：src/app/layout.tsx 是全局布局文件，所有页面都会继承这个布局（比如导航栏、页脚可以写在这里，不用每个页面重复写）。

至此，我们完成了项目的初始化和代码重构工作，包括：

用 create-next-app 搭好了基础框架，整理了项目结构
给项目整了个清晰的 src/ 目录结构，把业务代码和配置文件彻底分开
搞定了 Tailwind CSS 和 TypeScript 的基础配置
用 App Router 写了几个测试页面，验证了静态路由和动态路由的基本玩法，确保路由系统没问题
把 package.json 里的脚本命令和依赖都梳理了一遍，确保启动、打包这些核心流程都跑通

END

下一篇文章里，我们来重点对 ESLint + TypeScript 进行配置 —— 主要是 .eslint.config.mjs 和 tsconfig.json 这两个核心文件，了解每个配置项的含义和作用。

做好这些配置，能帮项目规避语法错误、提前揪出类型问题，避免后续写业务时踩坑；还能提升代码可读性和可维护性，贴合 Next.js 16 + TS 5.x 的适配需求。

我也是个跟着文档和AI交流一步步摸索的菜鸟，如果你对本文讲的项目初始化、路由这些内容有疑问，或者实操时踩了坑，欢迎在评论区留言。咱们一起交流避坑.

本文由mdnice多平台发布