编程马·菜鸟教程

Appearance

第3章：Next.js 项目创建与目录解析 ​

3.1 三种项目创建方式（新手推荐，适配不同场景） ​

方式1：npx create-next-app@latest 命令快速创建标准项目 ​

这是最推荐的方式，适合大多数场景，会创建一个包含所有核心功能的标准 Next.js 项目。

步骤：

  1. 打开终端：在你想要创建项目的目录中打开终端
  2. 运行命令：
    bash
    npx create-next-app@latest
  3. 回答配置问题：
    • 项目名称
    • 是否使用 TypeScript
    • 是否使用 ESLint
    • 是否使用 Tailwind CSS
    • 是否使用 src 目录
    • 是否使用 App Router（推荐）
    • 是否使用 Turbopack

示例：

bash
npx create-next-app@latest my-next-app
# 按照提示回答配置问题

方式2：使用官方模板创建特定场景项目（如博客、电商、Admin） ​

Next.js 官方提供了多种模板，适合特定场景的项目开发。

步骤：

  1. 访问 Vercel 模板库：打开 https://vercel.com/templates
  2. 选择 Next.js 模板：在模板列表中选择适合你需求的 Next.js 模板
  3. 创建项目：点击 "Deploy" 按钮，跟随向导创建项目
  4. 克隆项目：将创建的项目克隆到本地进行开发

常用模板：

  • Next.js Blog：博客网站模板
  • Next.js E-Commerce：电商网站模板
  • Next.js Admin：管理后台模板
  • Next.js Portfolio：作品集模板

方式3：手动初始化项目（了解项目核心依赖，加深理解） ​

这种方式适合想深入了解 Next.js 项目结构的开发者，手动创建项目文件和配置。

步骤：

  1. 创建项目目录：

    bash
    mkdir my-next-app
cd my-next-app

  2. 初始化 package.json：

    bash
    npm init -y

  3. 安装核心依赖：

    bash
    npm install next@latest react@latest react-dom@latest

  4. 创建基本文件结构：

    • package.json：配置脚本和依赖
    • app/：App Router 目录
    • public/：静态资源目录
    • next.config.js：Next.js 配置文件

  5. 配置 package.json：

json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}
  1. 创建基本页面：
    • app/page.js：首页
    • app/layout.js：布局

3.2 项目依赖安装与启动（npm install、npm run dev 等核心命令） ​

安装依赖 ​

使用 npm：

bash
npm install

使用 pnpm：

bash
pnpm install

使用 yarn：

bash
yarn install

启动开发服务器 ​

启动开发服务器：

bash
npm run dev
# 或
pnpm dev
# 或
yarn dev

指定端口：

bash
npm run dev -- -p 3001
# 或
pnpm dev -p 3001
# 或
yarn dev -p 3001

指定主机：

bash
npm run dev -- --host
# 或
pnpm dev --host
# 或
yarn dev --host

构建与部署 ​

构建项目：

bash
npm run build
# 或
pnpm build
# 或
yarn build

启动生产服务器：

bash
npm start
# 或
pnpm start
# 或
yarn start

3.3 项目目录结构逐文件解析（核心目录详解） ​

App Router 目录（app 目录，Next.js 14 推荐） ​

App Router 是 Next.js 13+ 引入的新路由系统，基于文件夹结构定义路由。

核心文件：

  • app/layout.js：根布局组件，应用于所有页面
  • app/page.js：首页组件
  • app/loading.js：全局加载状态组件
  • app/error.js：全局错误边界组件
  • app/not-found.js：404 页面组件

路由结构示例：

app/
├── layout.js         # 根布局
├── page.js           # 首页 (/)
├── about/
│   └── page.js       # 关于页 (/about)
├── blog/
│   ├── layout.js     # 博客布局
│   ├── page.js       # 博客列表页 (/blog)
│   └── [id]/
│       └── page.js   # 博客详情页 (/blog/1)
└── api/
    └── hello/
        └── route.js  # API 路由 (/api/hello)

Pages Router 目录（pages 目录，兼容旧版本，了解即可） ​

Pages Router 是 Next.js 13 之前的路由系统，基于文件命名定义路由。

核心文件：

  • pages/index.js：首页
  • pages/_app.js：应用入口
  • pages/_document.js：HTML 文档模板
  • pages/api/：API 路由目录

路由结构示例：

pages/
├── index.js         # 首页 (/)
├── about.js         # 关于页 (/about)
├── blog/            # 博客目录
│   ├── index.js     # 博客列表页 (/blog)
│   └── [id].js      # 博客详情页 (/blog/1)
└── api/
    └── hello.js     # API 路由 (/api/hello)

public 目录（静态资源存放） ​

用于存放静态资源，如图片、字体、图标等。

访问方式：

  • 直接通过 URL 访问，如 /images/logo.png
  • 在代码中使用 /images/logo.png 路径

components 目录（组件存放） ​

用于存放可复用的 React 组件。

组织方式：

  • 按功能分类：components/ui/、components/layout/、components/common/
  • 按页面分类：components/home/、components/blog/

lib 目录（工具函数、接口封装） ​

用于存放工具函数、API 接口封装、数据处理等逻辑。

常见文件：

  • lib/api.js：API 接口封装
  • lib/utils.js：工具函数
  • lib/constants.js：常量定义

config 目录（配置文件） ​

用于存放项目配置文件。

常见文件：

  • config/index.js：主配置文件
  • config/theme.js：主题配置
  • config/api.js：API 配置

3.4 配置文件核心（next.config.js 基础配置与进阶配置） ​

基础配置 ​

next.config.js 是 Next.js 项目的核心配置文件，位于项目根目录。

基本结构：

javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  swcMinify: true,
}

module.exports = nextConfig

进阶配置 ​

页面导出配置 ​

javascript
const nextConfig = {
  // 导出静态站点
  output: 'export',
  // 图片优化配置
  images: {
    unoptimized: true,
  },
}

环境变量配置 ​

javascript
const nextConfig = {
  env: {
    API_URL: process.env.API_URL,
  },
}

自定义 Webpack 配置 ​

javascript
const nextConfig = {
  webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
    // 自定义 Webpack 配置
    return config
  },
}

国际化配置 ​

javascript
const nextConfig = {
  i18n: {
    locales: ['en', 'zh'],
    defaultLocale: 'en',
  },
}

图片域名配置 ​

javascript
const nextConfig = {
  images: {
    domains: ['example.com', 'cdn.example.com'],
  },
}

3.5 环境变量配置（.env.local、.env.development、.env.production 区分） ​

环境变量文件 ​

Next.js 支持多种环境变量文件，用于不同环境的配置：

  • .env.local：本地开发环境变量，不会被提交到版本控制系统
  • .env.development：开发环境变量
  • .env.production：生产环境变量
  • .env：所有环境的通用变量

环境变量命名规则 ​

  • 客户端环境变量：以 NEXT_PUBLIC_ 前缀开头，会暴露给浏览器
  • 服务端环境变量：不以 NEXT_PUBLIC_ 前缀开头，仅在服务端使用

示例 ​

创建 .env.local 文件：

txt
# 服务端环境变量
API_SECRET_KEY=your-secret-key

# 客户端环境变量
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_NAME=My Next.js App

使用环境变量：

javascript
// 服务端
const secretKey = process.env.API_SECRET_KEY;

// 客户端
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
const appName = process.env.NEXT_PUBLIC_APP_NAME;

环境变量加载顺序 ​

Next.js 按以下顺序加载环境变量：

  1. .env.local（最高优先级）
  2. .env.development 或 .env.production（根据当前环境）
  3. .env（最低优先级）

小结 ​

本章介绍了 Next.js 项目的创建方法、目录结构和配置文件。通过本章的学习，你应该已经掌握了：

  1. 三种项目创建方式：使用 create-next-app、官方模板和手动初始化
  2. 核心命令：安装依赖、启动开发服务器、构建和部署
  3. 项目目录结构：App Router 目录、Pages Router 目录、public 目录、components 目录、lib 目录和 config 目录
  4. 配置文件：next.config.js 的基础配置和进阶配置
  5. 环境变量配置：不同环境的环境变量文件和使用方法

Next.js 的目录结构和配置文件是项目开发的基础，了解这些内容对于后续的开发非常重要。在实际开发中，建议使用 App Router（Next.js 14 推荐），它提供了更现代化的路由系统和更好的开发体验。

接下来，我们将学习 Next.js 的路由系统，这是 Next.js 的核心优势之一。

© 2026 编程马·菜鸟教程 版权所有

基于 VitePress 构建