一点放纵 發表於 2026-1-28 10:46:00

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

<h2 id="前言">前言</h2>
<p>作为一名长期深耕于外包公司的前端工程师，我大部分的项目都是使用 Vue2；此前学习的 Vue3 与 React，却始终没有机会在实际项目中落地实践。为了避免陷入颓废、被行业淘汰的困境，我计划着手搭建个人后台管理项目，全程记录使用 Next.js 的搭建流程，同时结合官方文档与 AI 工具，一步步完成项目落地，既巩固技术，也给自己的成长留下印记。</p>
<p><img src="https://img2024.cnblogs.com/blog/2938130/202601/2938130-20260128104632576-168759202.png" alt="" loading="lazy"></p>
<h2 id="0-开发环境及依赖版本">0 开发环境及依赖版本</h2>
<h3 id="开发环境">开发环境</h3>
<p>我这边开发环境选的是<code>Node.js + pnpm</code>组合。版本管理工具用的是 Volta，它最方便的地方就是能给不同项目配置不同的Node版本，不用来回切换麻烦。<br>
具体用法很简单，常用命令贴在这：</p>
<pre><code class="language-shell"># 将 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
</code></pre>
<p><code>pnpm</code> 的话，直接用 <code>npm install -g pnpm</code> 命令安装就行。</p>
<p>我现在用的 <code>Node.js</code>和 <code>pnpm</code>都是最新版本，做技术嘛，就得追着最新的来，后续用到的其他技术栈也会保持最新，同时兼顾好兼容性，避免出现版本不匹配的问题。</p>
<p>可以使用&nbsp;<code>node -v</code>、<code>pnpm -v</code> 查看版本号。<br>
<img src="https://img2024.cnblogs.com/blog/2938130/202601/2938130-20260128104632857-763764063.png" alt="" loading="lazy"></p>
<p>因为项目是使用 <code>Next</code> 官方脚手架创建项目，默认给你配置好了最新的、可兼容的版本，其他的依赖直接上新版！咱使用的版本号如下：</p>
<table>
<thead>
<tr>
<th>依赖</th>
<th>版本</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td>next</td>
<td>16.1.5</td>
<td>Next.js 框架</td>
</tr>
<tr>
<td>react</td>
<td>19.2.3</td>
<td>React 核心</td>
</tr>
<tr>
<td>react-dom</td>
<td>19.2.3</td>
<td>React DOM 渲染</td>
</tr>
<tr>
<td>typescript</td>
<td>^5</td>
<td>静态类型检查</td>
</tr>
<tr>
<td>eslint</td>
<td>^9</td>
<td>代码检查</td>
</tr>
<tr>
<td>eslint-config-next</td>
<td>16.1.5</td>
<td>Next.js ESLint 规则</td>
</tr>
<tr>
<td>tailwindcss</td>
<td>^4</td>
<td>原子化 CSS 框架</td>
</tr>
<tr>
<td>@tailwindcss/postcss</td>
<td>^4</td>
<td>Tailwind CSS 编译</td>
</tr>
</tbody>
</table>
<h2 id="1-初始化项目">1. 初始化项目</h2>
<h3 id="11-创建项目">1.1 创建项目</h3>
<p>这边我使用的 <code>Next.js</code> 官方推荐的 <code>create-next-app</code></p>
<pre><code class="language-shell">npx create-next-app@latest
</code></pre>
<p>安装时，你将看到以下提示</p>
<pre><code class="language-bash">? 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默认值吗，
&gt;   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.# 你想选择哪种代码检查工具
&gt;   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
</code></pre>
<h3 id="12-安装依赖">1.2 安装依赖</h3>
<p>使用 <code>VScode</code> 打开前面创建的项目 <code>my-app</code>,打开终端，输入 <code>pnpm install</code> 安装项目所需依赖。</p>
<p><img src="https://img2024.cnblogs.com/blog/2938130/202601/2938130-20260128104633184-979587798.png" alt="" loading="lazy"></p>
<h3 id="13-启动项目">1.3 启动项目</h3>
<p>查看 <code>package.json</code> 配置文件</p>
<pre><code class="language-json">{
...
"scripts": {
    "dev": "next dev", // 启动开发环境服务器
    "build": "next build", // 为生产环境构建 / 打包项目
    "start": "next start", // 启动生产环境服务器
    "lint": "eslint" // 运行代码检查工具
},
...
}
</code></pre>
<p>启动项目，测试是否运行成功：</p>
<pre><code class="language-shell">pnpm dev
</code></pre>
<p>项目正常启动后，在浏览器中访问<code>http://localhost:3000/</code></p>
<p>若页面能正常显示，且控制台不报任何异常，则项目创建启动成功。</p>
<p><img src="https://img2024.cnblogs.com/blog/2938130/202601/2938130-20260128104633616-1907596046.png" alt="" loading="lazy"></p>
<h2 id="2-调整项目结构">2. 调整项目结构</h2>
<h3 id="21-项目文件--文件夹作用全解析">2.1 项目文件 / 文件夹作用全解析</h3>
<pre><code class="language-ruby">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 # 项目核心配置文件
</code></pre>
<h3 id="22-创建测试页面">2.2 创建测试页面</h3>
<p>App Router 是<code>文件系统路由</code>，即「文件 / 文件夹的路径 = 页面的 URL 路径」。我们来创建一个 /test 测试页面：</p>
<ol>
<li>在 <code>src/app</code> 目录下，新建一个名为 test 的文件夹。</li>
<li>test 文件夹里，新建一个名为 <code>page.tsx</code> 的文件（这是 App Router 中 “页面文件” 的固定命名）。</li>
<li>在 <code>page.tsx</code> 中写入测试代码：</li>
</ol>
<pre><code class="language-typescript">// src/app/test/page.tsx
export default function TestPage() {
return (
    &lt;div style={{ padding: '2rem' }}&gt;
      &lt;h1&gt;这是一个测试页面&lt;/h1&gt;
      &lt;p&gt;访问路径：/test&lt;/p&gt;
    &lt;/div&gt;
);
}
</code></pre>
<p><img src="https://img2024.cnblogs.com/blog/2938130/202601/2938130-20260128104633972-539850188.png" alt="" loading="lazy"></p>
<h3 id="23-配置更多路由">2.3 配置更多路由</h3>
<p>如果你想快速体验多路由，还可以创建：</p>
<ul>
<li><strong>首页</strong>：<code>src/app/page.tsx</code> 就是默认的首页（访问路径 /），可以修改这个文件来定制首页内容。</li>
<li><strong>嵌套路由</strong>：比如创建 <code>src/app/blog//page.tsx</code>，就能实现动态路由 <code>/blog/123</code>（ 是动态参数）。</li>
<li><strong>全局布局</strong>：<code>src/app/layout.tsx</code> 是全局布局文件，所有页面都会继承这个布局（比如导航栏、页脚可以写在这里，不用每个页面重复写）。</li>
</ul>
<p>至此，我们完成了项目的初始化和代码重构工作，包括：</p>
<blockquote>
<ul>
<li>
<p>用 create-next-app 搭好了基础框架，整理了项目结构</p>
</li>
<li>
<p>给项目整了个清晰的 src/ 目录结构，把业务代码和配置文件彻底分开</p>
</li>
<li>
<p>搞定了 Tailwind CSS 和 TypeScript 的基础配置</p>
</li>
<li>
<p>用 App Router 写了几个测试页面，验证了静态路由和动态路由的基本玩法，确保路由系统没问题</p>
</li>
<li>
<p>把 package.json 里的脚本命令和依赖都梳理了一遍，确保启动、打包这些核心流程都跑通</p>
</li>
</ul>
</blockquote>
<h2 id="end">END</h2>
<p>下一篇文章里，我们来重点对 <code>ESLint + TypeScript</code> 进行配置 —— 主要是 <code>.eslint.config.mjs</code> 和 <code>tsconfig.json</code> 这两个核心文件，了解每个配置项的含义和作用。</p>
<p>做好这些配置，能帮项目规避语法错误、提前揪出类型问题，避免后续写业务时踩坑；还能提升代码可读性和可维护性，贴合 <code>Next.js 16 + TS 5.x</code> 的适配需求。</p>
<p>我也是个跟着文档和AI交流一步步摸索的菜鸟，如果你对本文讲的项目初始化、路由这些内容有疑问，或者实操时踩了坑，欢迎在评论区留言。咱们一起交流避坑.</p>
<p>本文由mdnice多平台发布</p><br><br>
来源：https://www.cnblogs.com/clbStudy/p/19542196
頁: [1]
查看完整版本: 2026 我的 Next.js 搭建之路（1）：初始化项目