1. 项目概述2026年Next.js已经成为现代Web开发的主流框架之一。这个系列文章将记录我从零开始搭建Next.js项目的完整过程首篇重点讲解如何正确初始化一个Next.js项目。作为React的元框架Next.js提供了开箱即用的服务端渲染、静态站点生成、API路由等强大功能让开发者能够快速构建高性能的Web应用。2. 环境准备2.1 Node.js版本选择Next.js 14要求Node.js 18.17.0或更高版本。建议使用nvm(Node Version Manager)管理Node版本nvm install 18 nvm use 18注意避免使用奇数版本(如19.x)这些通常是实验性版本可能存在稳定性问题。2.2 包管理器选择Next.js支持npm、yarn和pnpm。个人推荐pnpm因为它具有以下优势更快的安装速度磁盘空间效率更高(共享依赖)严格的依赖管理避免幽灵依赖安装pnpmnpm install -g pnpm3. 项目初始化3.1 创建项目运行以下命令创建新项目pnpm create next-applatest my-next-project创建过程中会提示配置选项项目名称默认当前目录名或可自定义TypeScript强烈建议选择YesESLint选择Yes保持代码规范Tailwind CSS根据项目需求选择src目录选择No使用默认结构实验性app目录选择Yes使用新的路由架构导入别名选择No保持默认3.2 项目结构解析初始化后的典型目录结构my-next-project/ ├── .next/ # 构建输出目录 ├── node_modules/ # 依赖 ├── public/ # 静态资源 │ └── favicon.ico ├── src/ │ ├── app/ # App Router │ │ ├── globals.css │ │ ├── layout.tsx # 根布局 │ │ └── page.tsx # 首页 │ └── styles/ # 样式文件 ├── .eslintrc.json # ESLint配置 ├── .gitignore # Git忽略规则 ├── next.config.js # Next.js配置 ├── package.json # 项目配置 ├── pnpm-lock.yaml # 依赖锁文件 └── tsconfig.json # TypeScript配置3.3 关键配置文件next.config.js- Next.js核心配置/** type {import(next).NextConfig} */ const nextConfig { reactStrictMode: true, swcMinify: true, experimental: { appDir: true, // 启用App Router }, } module.exports nextConfigtsconfig.json- TypeScript配置已针对Next.js优化{ compilerOptions: { target: es5, lib: [dom, dom.iterable, esnext], allowJs: true, skipLibCheck: true, strict: true, forceConsistentCasingInFileNames: true, noEmit: true, esModuleInterop: true, module: esnext, moduleResolution: node, resolveJsonModule: true, isolatedModules: true, jsx: preserve, incremental: true, baseUrl: ., paths: { /*: [./src/*] } }, include: [next-env.d.ts, **/*.ts, **/*.tsx], exclude: [node_modules] }4. 开发流程4.1 启动开发服务器pnpm dev开发服务器默认运行在http://localhost:3000具有热模块替换(HMR)快速刷新(Fast Refresh)错误覆盖层(Error Overlay)4.2 生产构建pnpm build构建过程会检查TypeScript类型运行ESLint生成生产优化代码创建静态资源(如适用)4.3 生产运行pnpm start使用生产优化的代码启动服务器。5. 核心概念配置5.1 路由系统Next.js 14提供两种路由系统Pages Router传统文件系统路由App Router基于React 18的新路由(推荐)App Router的关键特性布局共享嵌套路由流式渲染服务端组件默认5.2 数据获取Next.js提供多种数据获取方式// 服务端组件数据获取 async function getData() { const res await fetch(https://api.example.com/data) return res.json() } export default async function Page() { const data await getData() return div{data}/div }5.3 样式方案支持多种样式方案CSS Modules默认支持Tailwind CSS流行工具类方案Sass通过插件支持CSS-in-JS如styled-components6. 常见问题解决6.1 环境变量管理创建.env.local文件NEXT_PUBLIC_API_URLhttps://api.example.com SECRET_KEYyour-secret-keyNEXT_PUBLIC_前缀的变量会在客户端暴露其他变量仅在服务端可用6.2 跨域配置在next.config.js中配置const nextConfig { async headers() { return [ { source: /api/:path*, headers: [ { key: Access-Control-Allow-Origin, value: * }, { key: Access-Control-Allow-Methods, value: GET,POST,PUT,DELETE }, ], }, ] } }6.3 静态资源优化使用next/image组件优化图片import Image from next/image Image src/profile.jpg altProfile width{500} height{500} priority /7. 项目优化建议7.1 性能优化使用动态导入懒加载组件const DynamicComponent dynamic(() import(../components/HeavyComponent))预加载关键资源import Head from next/head Head link relpreload href/fonts/inter.woff2 asfont typefont/woff2 crossOriginanonymous / /Head7.2 安全实践内容安全策略(CSP)// next.config.js const nextConfig { async headers() { return [ { source: /(.*), headers: [ { key: Content-Security-Policy, value: default-src self; script-src self unsafe-inline, }, ], }, ] }, }禁用X-Powered-By头const nextConfig { poweredByHeader: false, }7.3 监控与分析集成Sentry错误监控pnpm add sentry/nextjs配置sentry.client.config.js和sentry.server.config.jsimport * as Sentry from sentry/nextjs Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, tracesSampleRate: 0.1, })8. 项目扩展8.1 国际化支持使用next-intl实现多语言pnpm add next-intl创建i18n配置// src/i18n.ts import { notFound } from next/navigation import { getRequestConfig } from next-intl/server const locales [en, zh] export default getRequestConfig(async ({ locale }) { if (!locales.includes(locale)) notFound() return { messages: (await import(../locales/${locale}.json)).default } })8.2 状态管理推荐使用Zustand轻量级状态库pnpm add zustand创建store// src/store/useStore.ts import { create } from zustand interface StoreState { count: number increment: () void } export const useStore createStoreState((set) ({ count: 0, increment: () set((state) ({ count: state.count 1 })), }))8.3 API路由创建API端点// src/app/api/hello/route.ts import { NextResponse } from next/server export async function GET() { return NextResponse.json({ message: Hello World }) }9. 部署策略9.1 Vercel部署安装Vercel CLIpnpm add -g vercel登录并部署vercel login vercel9.2 Docker化部署创建DockerfileFROM node:18-alpine AS builder WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN pnpm install COPY . . RUN pnpm build FROM node:18-alpine AS runner WORKDIR /app COPY --frombuilder /app/.next ./.next COPY --frombuilder /app/public ./public COPY --frombuilder /app/package.json ./package.json COPY --frombuilder /app/node_modules ./node_modules EXPOSE 3000 CMD [pnpm, start]构建并运行docker build -t my-next-app . docker run -p 3000:3000 my-next-app10. 开发体验优化10.1 VS Code配置.vscode/settings.json{ editor.codeActionsOnSave: { source.fixAll.eslint: true }, typescript.tsdk: node_modules/typescript/lib, eslint.validate: [typescript, typescriptreact] }10.2 调试配置.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Next.js: debug server-side, type: node-terminal, request: launch, command: pnpm dev }, { name: Next.js: debug client-side, type: chrome, request: launch, url: http://localhost:3000 } ] }10.3 代码生成工具使用Plop.js创建模板pnpm add -D plop创建plopfile.jsmodule.exports function (plop) { plop.setGenerator(component, { description: Create a new component, prompts: [{ type: input, name: name, message: Component name: }], actions: [{ type: add, path: src/components/{{pascalCase name}}/index.tsx, templateFile: plop-templates/component.hbs }] }) }11. 测试策略11.1 单元测试配置Jestpnpm add -D jest testing-library/react testing-library/jest-dom jest-environment-jsdomjest.config.jsmodule.exports { testEnvironment: jest-environment-jsdom, setupFilesAfterEnv: [rootDir/jest.setup.js], moduleNameMapper: { ^/(.*)$: rootDir/src/$1, }, }11.2 E2E测试使用Playwrightpnpm add -D playwright/test示例测试import { test, expect } from playwright/test test(homepage has title, async ({ page }) { await page.goto(http://localhost:3000) await expect(page).toHaveTitle(/Next.js App/) })12. 持续集成GitHub Actions配置.github/workflows/ci.ymlname: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: pnpm install - run: pnpm build - run: pnpm test13. 项目维护13.1 依赖更新使用npm-check-updatespnpm add -g npm-check-updates ncu -u pnpm install13.2 代码质量配置Husky和lint-stagedpnpm add -D husky lint-staged npx husky installpackage.json{ lint-staged: { *.{js,jsx,ts,tsx}: [eslint --fix, prettier --write] } }14. 性能监控使用Web Vitals// src/app/layout.tsx import { SpeedInsights } from vercel/speed-insights/next export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( html langen body {children} SpeedInsights / /body /html ) }15. 项目文档使用Next.js内置Markdown支持pnpm add remark remark-html gray-matter创建文档页面// src/app/docs/[...slug]/page.tsx import fs from fs import path from path import matter from gray-matter import { remark } from remark import html from remark-html export default async function DocPage({ params }: { params: { slug: string[] } }) { const filePath path.join(process.cwd(), docs, ...params.slug) .md const fileContents fs.readFileSync(filePath, utf8) const { data, content } matter(fileContents) const processedContent await remark().use(html).process(content) const contentHtml processedContent.toString() return ( article h1{data.title}/h1 div dangerouslySetInnerHTML{{ __html: contentHtml }} / /article ) }16. 项目升级Next.js升级步骤检查升级指南更新package.json中的版本运行测试解决破坏性变更pnpm add nextlatest reactlatest react-domlatest eslint-config-nextlatest17. 社区资源推荐学习资源Next.js官方文档Next.js GitHub仓库Vercel博客Next.js Conf视频Next.js Discord社区18. 项目架构建议18.1 目录结构优化推荐结构src/ ├── app/ # App Router ├── components/ # 共享组件 │ ├── ui/ # UI组件 │ └── features/ # 功能组件 ├── lib/ # 工具函数 ├── hooks/ # 自定义Hook ├── store/ # 状态管理 ├── styles/ # 全局样式 └── types/ # 类型定义18.2 组件设计原则单一职责原则组合优于继承明确props接口合理划分容器组件和展示组件19. 错误处理全局错误边界// src/app/error.tsx use client export default function ErrorBoundary({ error, reset, }: { error: Error reset: () void }) { return ( div h2Something went wrong!/h2 button onClick{() reset()}Try again/button /div ) }20. 项目收尾完成初始化后建议设置Git仓库编写README.md配置代码编辑器规划开发流程建立团队规范git init git add . git commit -m Initial commit with Next.js Next.js项目初始化与配置全指南
1. 项目概述2026年Next.js已经成为现代Web开发的主流框架之一。这个系列文章将记录我从零开始搭建Next.js项目的完整过程首篇重点讲解如何正确初始化一个Next.js项目。作为React的元框架Next.js提供了开箱即用的服务端渲染、静态站点生成、API路由等强大功能让开发者能够快速构建高性能的Web应用。2. 环境准备2.1 Node.js版本选择Next.js 14要求Node.js 18.17.0或更高版本。建议使用nvm(Node Version Manager)管理Node版本nvm install 18 nvm use 18注意避免使用奇数版本(如19.x)这些通常是实验性版本可能存在稳定性问题。2.2 包管理器选择Next.js支持npm、yarn和pnpm。个人推荐pnpm因为它具有以下优势更快的安装速度磁盘空间效率更高(共享依赖)严格的依赖管理避免幽灵依赖安装pnpmnpm install -g pnpm3. 项目初始化3.1 创建项目运行以下命令创建新项目pnpm create next-applatest my-next-project创建过程中会提示配置选项项目名称默认当前目录名或可自定义TypeScript强烈建议选择YesESLint选择Yes保持代码规范Tailwind CSS根据项目需求选择src目录选择No使用默认结构实验性app目录选择Yes使用新的路由架构导入别名选择No保持默认3.2 项目结构解析初始化后的典型目录结构my-next-project/ ├── .next/ # 构建输出目录 ├── node_modules/ # 依赖 ├── public/ # 静态资源 │ └── favicon.ico ├── src/ │ ├── app/ # App Router │ │ ├── globals.css │ │ ├── layout.tsx # 根布局 │ │ └── page.tsx # 首页 │ └── styles/ # 样式文件 ├── .eslintrc.json # ESLint配置 ├── .gitignore # Git忽略规则 ├── next.config.js # Next.js配置 ├── package.json # 项目配置 ├── pnpm-lock.yaml # 依赖锁文件 └── tsconfig.json # TypeScript配置3.3 关键配置文件next.config.js- Next.js核心配置/** type {import(next).NextConfig} */ const nextConfig { reactStrictMode: true, swcMinify: true, experimental: { appDir: true, // 启用App Router }, } module.exports nextConfigtsconfig.json- TypeScript配置已针对Next.js优化{ compilerOptions: { target: es5, lib: [dom, dom.iterable, esnext], allowJs: true, skipLibCheck: true, strict: true, forceConsistentCasingInFileNames: true, noEmit: true, esModuleInterop: true, module: esnext, moduleResolution: node, resolveJsonModule: true, isolatedModules: true, jsx: preserve, incremental: true, baseUrl: ., paths: { /*: [./src/*] } }, include: [next-env.d.ts, **/*.ts, **/*.tsx], exclude: [node_modules] }4. 开发流程4.1 启动开发服务器pnpm dev开发服务器默认运行在http://localhost:3000具有热模块替换(HMR)快速刷新(Fast Refresh)错误覆盖层(Error Overlay)4.2 生产构建pnpm build构建过程会检查TypeScript类型运行ESLint生成生产优化代码创建静态资源(如适用)4.3 生产运行pnpm start使用生产优化的代码启动服务器。5. 核心概念配置5.1 路由系统Next.js 14提供两种路由系统Pages Router传统文件系统路由App Router基于React 18的新路由(推荐)App Router的关键特性布局共享嵌套路由流式渲染服务端组件默认5.2 数据获取Next.js提供多种数据获取方式// 服务端组件数据获取 async function getData() { const res await fetch(https://api.example.com/data) return res.json() } export default async function Page() { const data await getData() return div{data}/div }5.3 样式方案支持多种样式方案CSS Modules默认支持Tailwind CSS流行工具类方案Sass通过插件支持CSS-in-JS如styled-components6. 常见问题解决6.1 环境变量管理创建.env.local文件NEXT_PUBLIC_API_URLhttps://api.example.com SECRET_KEYyour-secret-keyNEXT_PUBLIC_前缀的变量会在客户端暴露其他变量仅在服务端可用6.2 跨域配置在next.config.js中配置const nextConfig { async headers() { return [ { source: /api/:path*, headers: [ { key: Access-Control-Allow-Origin, value: * }, { key: Access-Control-Allow-Methods, value: GET,POST,PUT,DELETE }, ], }, ] } }6.3 静态资源优化使用next/image组件优化图片import Image from next/image Image src/profile.jpg altProfile width{500} height{500} priority /7. 项目优化建议7.1 性能优化使用动态导入懒加载组件const DynamicComponent dynamic(() import(../components/HeavyComponent))预加载关键资源import Head from next/head Head link relpreload href/fonts/inter.woff2 asfont typefont/woff2 crossOriginanonymous / /Head7.2 安全实践内容安全策略(CSP)// next.config.js const nextConfig { async headers() { return [ { source: /(.*), headers: [ { key: Content-Security-Policy, value: default-src self; script-src self unsafe-inline, }, ], }, ] }, }禁用X-Powered-By头const nextConfig { poweredByHeader: false, }7.3 监控与分析集成Sentry错误监控pnpm add sentry/nextjs配置sentry.client.config.js和sentry.server.config.jsimport * as Sentry from sentry/nextjs Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, tracesSampleRate: 0.1, })8. 项目扩展8.1 国际化支持使用next-intl实现多语言pnpm add next-intl创建i18n配置// src/i18n.ts import { notFound } from next/navigation import { getRequestConfig } from next-intl/server const locales [en, zh] export default getRequestConfig(async ({ locale }) { if (!locales.includes(locale)) notFound() return { messages: (await import(../locales/${locale}.json)).default } })8.2 状态管理推荐使用Zustand轻量级状态库pnpm add zustand创建store// src/store/useStore.ts import { create } from zustand interface StoreState { count: number increment: () void } export const useStore createStoreState((set) ({ count: 0, increment: () set((state) ({ count: state.count 1 })), }))8.3 API路由创建API端点// src/app/api/hello/route.ts import { NextResponse } from next/server export async function GET() { return NextResponse.json({ message: Hello World }) }9. 部署策略9.1 Vercel部署安装Vercel CLIpnpm add -g vercel登录并部署vercel login vercel9.2 Docker化部署创建DockerfileFROM node:18-alpine AS builder WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN pnpm install COPY . . RUN pnpm build FROM node:18-alpine AS runner WORKDIR /app COPY --frombuilder /app/.next ./.next COPY --frombuilder /app/public ./public COPY --frombuilder /app/package.json ./package.json COPY --frombuilder /app/node_modules ./node_modules EXPOSE 3000 CMD [pnpm, start]构建并运行docker build -t my-next-app . docker run -p 3000:3000 my-next-app10. 开发体验优化10.1 VS Code配置.vscode/settings.json{ editor.codeActionsOnSave: { source.fixAll.eslint: true }, typescript.tsdk: node_modules/typescript/lib, eslint.validate: [typescript, typescriptreact] }10.2 调试配置.vscode/launch.json{ version: 0.2.0, configurations: [ { name: Next.js: debug server-side, type: node-terminal, request: launch, command: pnpm dev }, { name: Next.js: debug client-side, type: chrome, request: launch, url: http://localhost:3000 } ] }10.3 代码生成工具使用Plop.js创建模板pnpm add -D plop创建plopfile.jsmodule.exports function (plop) { plop.setGenerator(component, { description: Create a new component, prompts: [{ type: input, name: name, message: Component name: }], actions: [{ type: add, path: src/components/{{pascalCase name}}/index.tsx, templateFile: plop-templates/component.hbs }] }) }11. 测试策略11.1 单元测试配置Jestpnpm add -D jest testing-library/react testing-library/jest-dom jest-environment-jsdomjest.config.jsmodule.exports { testEnvironment: jest-environment-jsdom, setupFilesAfterEnv: [rootDir/jest.setup.js], moduleNameMapper: { ^/(.*)$: rootDir/src/$1, }, }11.2 E2E测试使用Playwrightpnpm add -D playwright/test示例测试import { test, expect } from playwright/test test(homepage has title, async ({ page }) { await page.goto(http://localhost:3000) await expect(page).toHaveTitle(/Next.js App/) })12. 持续集成GitHub Actions配置.github/workflows/ci.ymlname: CI on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: pnpm install - run: pnpm build - run: pnpm test13. 项目维护13.1 依赖更新使用npm-check-updatespnpm add -g npm-check-updates ncu -u pnpm install13.2 代码质量配置Husky和lint-stagedpnpm add -D husky lint-staged npx husky installpackage.json{ lint-staged: { *.{js,jsx,ts,tsx}: [eslint --fix, prettier --write] } }14. 性能监控使用Web Vitals// src/app/layout.tsx import { SpeedInsights } from vercel/speed-insights/next export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( html langen body {children} SpeedInsights / /body /html ) }15. 项目文档使用Next.js内置Markdown支持pnpm add remark remark-html gray-matter创建文档页面// src/app/docs/[...slug]/page.tsx import fs from fs import path from path import matter from gray-matter import { remark } from remark import html from remark-html export default async function DocPage({ params }: { params: { slug: string[] } }) { const filePath path.join(process.cwd(), docs, ...params.slug) .md const fileContents fs.readFileSync(filePath, utf8) const { data, content } matter(fileContents) const processedContent await remark().use(html).process(content) const contentHtml processedContent.toString() return ( article h1{data.title}/h1 div dangerouslySetInnerHTML{{ __html: contentHtml }} / /article ) }16. 项目升级Next.js升级步骤检查升级指南更新package.json中的版本运行测试解决破坏性变更pnpm add nextlatest reactlatest react-domlatest eslint-config-nextlatest17. 社区资源推荐学习资源Next.js官方文档Next.js GitHub仓库Vercel博客Next.js Conf视频Next.js Discord社区18. 项目架构建议18.1 目录结构优化推荐结构src/ ├── app/ # App Router ├── components/ # 共享组件 │ ├── ui/ # UI组件 │ └── features/ # 功能组件 ├── lib/ # 工具函数 ├── hooks/ # 自定义Hook ├── store/ # 状态管理 ├── styles/ # 全局样式 └── types/ # 类型定义18.2 组件设计原则单一职责原则组合优于继承明确props接口合理划分容器组件和展示组件19. 错误处理全局错误边界// src/app/error.tsx use client export default function ErrorBoundary({ error, reset, }: { error: Error reset: () void }) { return ( div h2Something went wrong!/h2 button onClick{() reset()}Try again/button /div ) }20. 项目收尾完成初始化后建议设置Git仓库编写README.md配置代码编辑器规划开发流程建立团队规范git init git add . git commit -m Initial commit with Next.js