要点

先确认 Node、包管理器和工程目录，再创建应用。锁文件记录依赖解析结果，脚手架版本与最终依赖版本并不是同一个概念。

概述

本章的产物是一个有锁文件、明确 Node 版本、能独立运行 lint、类型检查和开发服务器的应用。编辑器扩展和镜像是可选辅助工具，不是项目能否构建的前提。

系统要求

最低要求

• Node.js: 20.9.0 或更高版本；本仓当前复现基线为 Node 24
• 操作系统: Windows 10+, macOS 10.15+, Linux
• 内存: 推荐使用8GB 以上
• 存储空间: 10GB 可用空间
• 网络连接: 安装软件包时需要

推荐配置

• Node.js: Node 24（使用受支持的当前 LTS/维护线；项目实际要求仍以 package.json 的 engines 为准）
• 包管理器: Corepack 管理的 pnpm 11，或项目锁文件指定的包管理器版本
• IDE: VS Code 1.80+ 推荐扩展
• 终端: 支持 UTF-8的现代 Shell
• 浏览器: Chrome/Firefox 最新版本用于开发

安装步骤

1. 安装 Node.js

macOS (使用 Homebrew)

# 如果尚未安装Homebrew，先安装它
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. 安装 Node 24
brew install node@24

1. 验证安装
node --version
npm --version

Windows (使用 Winget)

# 安装 Node 24
winget install OpenJS.NodeJS.24

1. 验证安装
node --version
npm --version

Linux (Ubuntu/Debian)

# 使用 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

1. 验证安装
node --version
npm --version

替代方案：使用 Node 版本管理器(nvm)

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

1. 重新加载Shell
source ~/.bashrc

1. 安装并使用 Node 24
nvm install 24
nvm use 24
nvm alias default 24

1. 验证安装
node --version
npm --version

2. 安装包管理器

推荐：pnpm

# 启用 Corepack；随后由项目 packageManager 字段或 lock 文件决定 pnpm 版本。
corepack enable
pnpm --version

1. 若当前 Node 发行版没有可用的 Corepack，再按 pnpm 官方安装页选择安装方式。
curl -fsSL https://get.pnpm.io/install.sh | sh

1. 验证安装
pnpm --version

配置 npm 镜像（中国大陆用户）

# 设置npm镜像以加快下载速度
npm config set registry https://registry.npmmirror.com

1. 设置pnpm镜像
pnpm config set registry https://registry.npmmirror.com

1. 验证镜像设置
npm config get registry
pnpm config get registry

替代方案：Yarn（如果偏好）

# 全局安装Yarn
npm install -g yarn

1. 验证安装
yarn --version

3. 安装代码编辑器

VS Code 安装

# macOS
brew install --cask visual-studio-code

1. Windows (Winget)
winget install Microsoft.VisualStudioCode

1. Linux (Ubuntu)
sudo snap install --classic code

必需的 VS Code 扩展

# 安装推荐的扩展
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension dbaeumer.vscode-eslint
code --install-extension ms-vscode.vscode-json
code --install-extension ms-vscode.vscode-react-hooks

4. 创建 Next.js 项目

使用 create-next-app

# 创建新的 Next.js 项目。首次运行会交互询问选项；也可以按下一行显式传参。
npx create-next-app@latest my-nextjs-app --typescript --tailwind --app --src-dir --import-alias "@/*"

1. 或者使用pnpm
pnpm create next-app my-nextjs-app --typescript --tailwind --app --src-dir --import-alias "@/*"

1. 进入项目目录
cd my-nextjs-app

1. 立即记录脚手架实际写入的版本；后续学习与排错都以它们和锁文件为准。
npm ls next react react-dom typescript
git init
git add package.json package-lock.json
git commit -m "chore: scaffold next app"

create-next-app@latest 适合开始一次新脚手架尝试，但它的模板和依赖会随日期改变。要复现本章练习，保存首次生成的 package.json 与 lock 文件；团队项目应在约定的脚手架版本和 Node 版本下生成，再由升级任务显式变更。不要把命令里的 latest 误解成项目会持续自动升级。

项目选项说明

• --typescript: 使用 TypeScript 确保类型安全
• --tailwind: 集成 Tailwind CSS 进行样式
• --app: 使用 App Router（Next.js 13+推荐）
• --src-dir: 使用 src 目录结构
• --import-alias "@/*": 设置路径别名以实现更清晰的导入

5. 配置开发环境

安装项目依赖

# 使用npm
npm install

1. 使用pnpm
pnpm install

1. 使用yarn
yarn install

启动开发服务器

# 使用npm
npm run dev

1. 使用pnpm
pnpm dev

1. 使用yarn
yarn dev

访问 http://localhost:3000 查看应用程序。

环境配置文件

1. package.json：先理解脚本，不要手抄依赖版本

create-next-app 已经生成和它的模板相匹配的依赖、ESLint 配置与 lock 文件。下面只展示一个项目至少应理解的脚本形状；不要把这段片段覆盖到脚手架生成的 package.json，也不要混用来自不同教程的 Next、React、ESLint 版本。

{
  "name": "my-nextjs-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "type-check": "tsc --noEmit",
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

Next 16 的 next build 不再自动运行 lint，所以把 npm run lint 作为独立门槛。npm run type-check 也可先于构建执行，便于把类型问题与打包问题分开定位。官方的 安装说明 给出当前脚手架选项和最低 Node 要求。

2. tsconfig.json

{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/styles/*": ["./src/styles/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

3. next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 只在项目确实需要 next/image 远程来源限制时保留此项。
  images: {
    // Next.js 16：使用 remotePatterns 描述允许的远程图片来源。
    remotePatterns: [{ protocol: 'https', hostname: 'example.com' }],
  },
}

module.exports = nextConfig

4. .env.local

# 应用程序配置
NEXT_PUBLIC_APP_NAME="我的Next.js应用"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

1. API配置
NEXT_PUBLIC_API_URL="http://localhost:3001/api"
DATABASE_URL="postgresql://用户名:密码@localhost:5432/数据库"

1. 认证配置
NEXTAUTH_SECRET="你的nextauth密钥"
NEXTAUTH_URL="http://localhost:3000"

1. 功能标志
NEXT_PUBLIC_ENABLE_ANALYTICS=false
NEXT_PUBLIC_ENABLE_DEBUG=true

开发工具配置

1. ESLint 配置

Next 16 已移除 next lint 和 next.config.* 的 eslint 选项。新项目优先保留脚手架生成的 eslint.config.mjs；若从零创建一个平坦配置，可以使用：

// eslint.config.mjs
import nextVitals from 'eslint-config-next/core-web-vitals'
import nextTypeScript from 'eslint-config-next/typescript'

export default [...nextVitals, ...nextTypeScript]

再运行 npm run lint。项目已有 ESLint 配置时，不要直接覆盖它；应先合并规则并运行 lint，确认没有把现有忽略文件或自定义规则删掉。配置迁移细节见 Next.js ESLint 文档。

2. Prettier 配置

创建.prettierrc:

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

创建.prettierignore:

.next/
out/
dist/
build/
node_modules/
*.min.js
*.min.css

3. Git 配置

创建.gitignore:

# 依赖
node_modules/
.pnp
.pnp.js

1. 测试
coverage/

1. Next.js
.next/
out/

1. 生产
build/

1. 杂项
.DS_Store
*.pem

1. 调试
npm-debug.log*
yarn-debug.log*
yarn-error.log*

1. 本地环境文件
.env*.local

1. Vercel
.vercel

1. TypeScript
*.tsbuildinfo
next-env.d.ts

1. IDE
.vscode/
.idea/

1. 操作系统
Thumbs.db

4. VS Code 工作区配置

创建.vscode/settings.json:

{
  "typescript.preferences.preferTypeOnlyAutoImports": true,
  "typescript.suggest.autoImports": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  },
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/.next": true,
    "**/dist": true
  },
  "typescript.preferences.includePackageJsonAutoImports": "on"
}

创建.vscode/extensions.json:

{
  "recommendations": [
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "ms-vscode.vscode-json",
    "ms-vscode.vscode-react-hooks",
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense"
  ]
}

创建.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    }
  ]
}

创建.vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "启动Next.js开发服务器",
      "type": "shell",
      "command": "npm run dev",
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "new"
      }
    },
    {
      "label": "运行类型检查",
      "type": "shell",
      "command": "npm run type-check",
      "group": "test"
    },
    {
      "label": "格式化代码",
      "type": "shell",
      "command": "npm run format",
      "group": "build"
    }
  ]
}

开发工作流程

1. 日常开发命令

# 启动开发服务器
npm run dev

1. 类型检查
npm run type-check

1. 代码检查
npm run lint

1. 格式化代码
npm run format

1. 构建生产版本
npm run build

1. 启动生产服务器
npm run start

2. Git 工作流程

# 初始化仓库
git init

1. 添加文件
git add .

1. 初始提交
git commit -m "初始提交：Next.js 16项目设置"

1. 创建功能分支
git checkout -b feature/new-feature

1. 添加更改并提交
git add .
git commit -m "功能：添加新功能"

1. 推送到远程仓库
git push origin feature/new-feature

1. 合并到主分支
git checkout main
git merge feature/new-feature

3. 项目结构

my-nextjs-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── globals.css
│   ├── components/
│   │   ├── ui/
│   │   └── features/
│   ├── lib/
│   │   ├── utils.ts
│   │   └── types.ts
│   └── styles/
├── public/
├── .next/
├── .gitignore
├── eslint.config.mjs
├── .prettierrc
├── next.config.js
├── tsconfig.json
├── tailwind.config.js
└── package.json

高级配置

1. package.json 中的自定义脚本

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "lint:fix": "eslint --fix",
    "type-check": "tsc --noEmit",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "analyze": "ANALYZE=true next build",
    "postinstall": "prisma generate"
  }
}

2. 环境特定配置

// next.config.js
const isProduction = process.env.NODE_ENV === 'production'

const nextConfig = {
  // Next 16 默认使用 Turbopack。只有项目必须依赖 webpack 插件或回调时，
  // 才配置 webpack，并把对应脚本明确写成 next dev --webpack / next build --webpack。
  ...(isProduction && {
    compiler: {
      removeConsole: true,
    },
  }),
}

module.exports = nextConfig

常见问题解决

1. Node.js 版本问题

# 检查当前Node.js版本
node --version

1. 使用 nvm 管理版本；这里应使用项目要求的主版本。
nvm list
nvm use 24

1. 清除npm缓存
npm cache clean --force

2. 权限问题

# 修复npm权限（macOS/Linux）
sudo chown -R $(whoami) ~/.npm

1. 修复全局npm目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

3. 端口冲突

# 查找使用端口3000的进程
lsof -i :3000

1. 确认是自己的开发服务后，填入 lsof 输出中的进程号再发送终止信号
TARGET_PID=""
kill -TERM "${TARGET_PID:?请先填写开发服务的PID}"

1. 或者使用不同端口
npm run dev -- -p 3001

4. 内存问题

# 增加Node.js内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

1. 或者在package.json脚本中
"dev": "NODE_OPTIONS='--max-old-space-size=4096' next dev"

5. 依赖问题

# 清除node_modules并重新安装
rm -rf node_modules package-lock.json
npm install

1. 清除pnpm缓存
pnpm store prune
pnpm install

1. 强制清理安装
npm ci

开发最佳实践

环境搭好后应能从干净目录安装、检查、构建并运行一个最小页面。src 目录和按功能分组有助定位代码，但不自动保证可维护；先把页面入口、复用组件与服务端代码边界说明白。

版本控制保存可解释的改动与依赖锁文件，升级按兼容性和维护需求进行。TypeScript 严格模式检查类型，lint 检查已配置规则，格式化统一文本，它们不等于性能优化或运行时验证。构建速度与首屏性能分别测量，不把换构建器当作全部问题的解法。

快速入门检查清单

• [ ] 安装项目所需的 Node 版本（本仓基线为 Node 24）
• [ ] 安装 pnpm 包管理器
• [ ] 安装 VS Code 及扩展
• [ ] 创建 Next.js 16项目
• [ ] 配置开发环境
• [ ] 设置 Git 仓库
• [ ] 验证所有配置正常工作
• [ ] 运行开发服务器
• [ ] 创建第一个组件
• [ ] 提交初始代码

下一步

完成环境搭建后，你可以继续学习：

1. TypeScript 基础 – 掌握 TypeScript 核心概念
2. React 基础 – 学习 React 组件开发
3. Next.js 路由 – 理解 App Router 系统
4. 样式解决方案 – 掌握 Tailwind CSS 和现代样式
5. 数据获取 – 学习服务端渲染和 API 路由
6. 部署 – 将应用程序部署到生产环境

交叉引用

附加资源

文档

• Next.js 官方文档
• Node.js 文档
• TypeScript 手册
• VS Code 文档

工具和扩展

• VS Code 扩展市场
• Node 版本管理器(nvm)
• pnpm 文档
• Tailwind CSS

社区资源

• Next.js GitHub
• React 社区
• TypeScript 社区
• Stack Overflow

文档交叉引用

相关文档

• 第一个 Next.js 应用
• Next.js 与 TypeScript
• Next.js 布局与路由
• Next.js 样式与 Tailwind
• Next.js 数据获取基础

参考章节

• 📖 [本模块其他章节]: 创建第一个 Next.js 应用 | TypeScript 集成
• 📖 [Knowledge Points 快速参考]: 开发工具配置 | JavaScript 现代语法

总结

核心要点回顾

1. Node.js 环境: 掌握 Node.js 的安装方法和版本管理，理解为什么需要20.9+版本
2. 包管理器选择: 学会使用 npm、pnpm 等包管理器，了解镜像配置和依赖管理
3. IDE 配置: 掌握 VS Code 的安装和必需扩展配置，提升开发效率
4. 项目创建: 使用 create-next-app 快速创建 Next.js 项目，理解各种配置选项
5. 开发工具: 配置 ESLint、Prettier 等代码质量工具，建立标准化开发流程

学习成果检查

• [ ] 是否成功安装项目所需 Node 版本并能验证版本？
• [ ] 是否掌握至少一种包管理器的基本使用方法？
• [ ] 是否能够成功创建 Next.js 16项目并启动开发服务器？
• [ ] 是否理解项目结构中各个配置文件的作用？
• [ ] 是否能够配置基本的开发工具和代码规范？

贡献与反馈

内容改进

如果你发现本文档有改进空间，欢迎： – 🐛 报告问题: 在 Issues 中提出具体问题 – 💡 建议改进: 提出修改建议和补充内容 – 📝 参与贡献: 提交 PR 完善文档内容

学习反馈

分享你的学习体验： – ✅ 有用内容: 哪些部分对你最有帮助 – ❓ 疑问点: 哪些内容需要进一步澄清 – 🎯 建议: 希望增加什么内容

文档状态: ✅ 已完成最后更新: 2026年9月版本: v1.0.0