跳到主要内容

环境配置

本章将介绍如何搭建 Next.js 开发环境，创建第一个 Next.js 项目。

前置要求​

在开始之前，请确保你的系统已安装：

  • Node.js：18.18 或更高版本
  • 包管理器：npm、yarn、pnpm 或 bun
  • 代码编辑器：推荐 VS Code

检查 Node.js 版本​

node -v
# 应该显示 v18.18.0 或更高版本

安装 Node.js​

如果尚未安装 Node.js，推荐使用以下方式：

方式一：官网下载

访问 Node.js 官网，下载 LTS 版本。

方式二：使用 nvm（推荐）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js
nvm install --lts

# 使用 LTS 版本
nvm use --lts

创建项目​

使用 create-next-app​

Next.js 提供了官方脚手架工具 create-next-app，可以快速创建新项目：

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

交互式配置​

运行命令后，会提示选择配置选项：

What is your project named? my-next-app
Would you like to use TypeScript? No / Yes
Would you like to use ESLint? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would you like your code inside a `src/` directory? No / Yes
Would you like to use App Router? No / Yes
Would you like to use Turbopack for `next dev`? No / Yes
Would you like to customize the import alias? No / Yes

推荐配置​

对于新项目，推荐以下配置：

  • TypeScript：Yes（类型安全）
  • ESLint：Yes（代码规范）
  • Tailwind CSS：Yes（样式方案）
  • src/ 目录：Yes（代码组织）
  • App Router：Yes（新路由系统）
  • Turbopack：Yes（更快的开发体验）

一键创建​

也可以通过命令行参数直接指定配置：

npx create-next-app@latest my-next-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --turbopack \
  --import-alias "@/*"

项目结构​

创建完成后，项目结构如下：

my-next-app/
├── src/
│   └── app/
│       ├── favicon.ico
│       ├── globals.css
│       ├── layout.tsx
│       └── page.tsx
├── public/
│   └── images/
├── .eslintrc.json
├── .gitignore
├── next.config.ts
├── package.json
├── postcss.config.mjs
├── README.md
├── tailwind.config.ts
└── tsconfig.json

目录说明​

目录/文件说明
src/app/App Router 核心目录，存放页面和布局
src/app/page.tsx首页组件（路由 /）
src/app/layout.tsx根布局组件
src/app/globals.css全局样式文件
public/静态资源目录
next.config.tsNext.js 配置文件
tailwind.config.tsTailwind CSS 配置
tsconfig.jsonTypeScript 配置

启动开发服务器​

进入项目目录，启动开发服务器：

cd my-next-app
npm run dev

终端会显示：

   ▲ Next.js 15.0.0
   - Local:        http://localhost:3000
   - Environments: .env

 ✓ Starting...
 ✓ Ready in 1.2s

打开浏览器访问 http://localhost:3000，你将看到 Next.js 欢迎页面。

核心文件解析​

page.tsx - 页面组件​

// src/app/page.tsx
export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center">
      <h1 className="text-4xl font-bold">Hello Next.js!</h1>
    </main>
  );
}

说明：

  • page.tsx 是路由页面组件
  • 文件位置决定路由路径
  • 必须默认导出一个 React 组件

layout.tsx - 布局组件​

// src/app/layout.tsx
import type { Metadata } from "next";
import "./globals.css";

export const metadata: Metadata = {
  title: "我的 Next.js 应用",
  description: "使用 Next.js 构建",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  );
}

说明：

  • layout.tsx 定义页面共享布局
  • 根布局必须包含 <html> 和 <body> 标签
  • 可以定义页面元数据（metadata）

globals.css - 全局样式​

/* src/app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 自定义全局样式 */
body {
  font-family: system-ui, sans-serif;
}

Turbopack 详解​

Turbopack 是 Next.js 15 及更高版本的默认构建工具，专为 JavaScript 和 TypeScript 优化的增量打包器，使用 Rust 编写。

为什么选择 Turbopack？​

Turbopack 解决了传统打包工具的几个核心问题：

统一的依赖图：Next.js 支持多种输出环境（客户端和服务端），管理多个编译器并拼接打包结果非常繁琐。Turbopack 使用单一的统一依赖图处理所有环境。

打包 vs 原生 ESM：一些工具在开发时跳过打包，依赖浏览器的原生 ESM。这对小型应用有效，但大型应用会因为过多的网络请求而变慢。Turbopack 在开发时进行打包，但采用优化方式保持大型应用的快速响应。

增量计算：Turbopack 跨核心并行工作，并将结果缓存到函数级别。一旦完成某项工作，Turbopack 不会重复执行。

延迟打包：Turbopack 只打包开发服务器实际请求的内容。这种延迟方法可以减少初始编译时间和内存使用。

默认启用​

从 Next.js 16 开始，Turbopack 是默认的打包器：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

如需使用 Webpack，可以通过 --webpack 标志切换：

{
  "scripts": {
    "dev": "next dev --webpack",
    "build": "next build --webpack"
  }
}

支持的功能​

Turbopack 对常见用例提供零配置支持：

功能类别特性支持状态
语言JavaScript、TypeScript✅ 使用 SWC 编译
ESNext 特性✅ 支持 SWC 覆盖的所有特性
CommonJS (require)✅
ESM (静态/动态 import)✅
Babel✅ 检测到配置文件自动启用
ReactJSX/TSX✅
Fast Refresh✅ 无需配置
React Server Components✅
样式全局 CSS✅
CSS Modules✅ 使用 Lightning CSS
CSS 嵌套✅
PostCSS✅ 自动处理配置文件
Sass/SCSS✅ 开箱即用
资源静态资源（图片、字体）✅
JSON 导入✅
解析路径别名✅ 读取 tsconfig.json
手动别名✅ 可配置
自定义扩展名✅ 可配置

与 Webpack 的主要差异​

文件系统根目录：Turbopack 使用根目录解析模块。项目根目录外的文件默认不会被解析。如果使用 npm link 链接依赖，需要配置根目录选项。

CSS Modules 顺序：Turbopack 遵循 JS 导入顺序来排列 CSS Modules。如果样式顺序有问题，可以使用 @import 强制顺序。

Sass 导入语法：Turbopack 不支持 Webpack 的旧版 ~ 语法。需要将 @import '~bootstrap/...' 改为 @import 'bootstrap/...'。

Webpack 插件：Turbopack 不支持 Webpack 插件。依赖插件的工具需要寻找替代方案或继续使用 Webpack。

配置选项​

在 next.config.ts 中配置 Turbopack：

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  turbopack: {
    // 路径别名
    resolveAlias: {
      underscore: "lodash",
      "@components": "./src/components",
    },
    // 自定义扩展名
    resolveExtensions: [".mdx", ".tsx", ".ts", ".jsx", ".js", ".json"],
  },
};

export default nextConfig;

性能调试​

如遇到性能或内存问题，可以生成追踪文件：

NEXT_TURBOPACK_TRACING=1 npm run dev

这会在 .next/dev/trace-turbopack 生成追踪文件，可用于向 Next.js 团队报告问题。

版本历史​

版本变更
Next.js 16.0Turbopack 成为默认打包器
Next.js 15.5Turbopack 构建支持（Beta）
Next.js 15.0Turbopack 开发模式稳定
Next.js 13Turbopack 实验性引入

常用命令​

开发命令​

# 启动开发服务器（默认使用 Turbopack）
npm run dev

# 启动开发服务器（指定端口）
npm run dev -- -p 4000

# 使用 Webpack 而非 Turbopack
npm run dev -- --webpack

构建命令​

# 构建生产版本
npm run build

# 启动生产服务器
npm run start

# 导出静态站点
npm run build && npm run export

其他命令​

# 代码检查
npm run lint

# 类型检查
npx tsc --noEmit

VS Code 配置​

推荐扩展​

安装以下 VS Code 扩展提升开发体验：

  1. Next.js snippets：代码片段
  2. Tailwind CSS IntelliSense：Tailwind 智能提示
  3. ESLint：代码规范检查
  4. Prettier：代码格式化

settings.json 配置​

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

环境变量​

Next.js 支持环境变量，创建 .env.local 文件：

# .env.local
DATABASE_URL="postgresql://localhost:5432/mydb"
API_KEY="your-api-key"

# 客户端可访问的环境变量（以 NEXT_PUBLIC_ 开头）
NEXT_PUBLIC_API_URL="https://api.example.com"

使用环境变量​

// 服务端使用
console.log(process.env.DATABASE_URL);

// 客户端使用
console.log(process.env.NEXT_PUBLIC_API_URL);
安全提示

不要将敏感信息放在 NEXT_PUBLIC_ 开头的环境变量中，这些变量会被打包到客户端代码中。

小结​

本章我们学习了：

  1. 安装 Node.js 和配置开发环境
  2. 使用 create-next-app 创建项目
  3. 理解项目结构和核心文件
  4. 启动开发服务器
  5. 配置 VS Code 开发环境
  6. 使用环境变量

练习​

  1. 创建一个新的 Next.js 项目，使用 TypeScript 和 Tailwind CSS
  2. 修改首页内容，显示你的名字和一段介绍
  3. 添加一个环境变量并在页面中显示
  4. 尝试修改布局组件，添加一个页脚