Next.js 15从零搭建实战：一个教程解决所有踩坑问题

作者： /

环境准备：Node.js 版本是个坑

先看环境配置。很多人直接 npm install next 就开始写代码，然后报错一堆。官方文档写着”支持 Node.js 18+”，但实际 18.17 以下版本会有各种奇葩问题。

“bash

我的血泪教训：必须用 Node.js 18.17 以上

node -v # 确认版本

创建项目（推荐用 create-next-app）

npx create-next-app@latest my-app --typescript --tailwind --eslint
`

为什么要这么写？因为 –typescript 是必须的，Next.js 15 对 TS 的支持更好；–tailwind 省去手动配置 CSS 框架；–eslint 自动集成代码检查。这个组合拳能让你少写 50 行配置代码。

路由设计：App Router 不是万能的

另一个坑是路由设计。Next.js 13 以后主推 App Router，但很多人直接照搬 Pages Router 的写法，结果在中间件和布局上翻车。

先看文件结构：
`
my-app/
├── app/
│ ├── layout.tsx # 全局布局
│ ├── page.tsx # 首页
│ ├── (auth)/ # 路由组（带括号）
│ │ ├── login/page.tsx
│ │ └── register/page.tsx
│ ├── dashboard/ # 动态路由
│ │ ├── layout.tsx
│ │ ├── [id]/page.tsx
│ │ └── loading.tsx # 自动加载状态
│ └── api/ # API 路由
│ └── users/route.ts
`

关键点：layout.tsx 可以嵌套，但别忘了 (auth) 这种路由组不会改变 URL 路径。我一开始以为括号是修饰符，结果调试半天。

`typescript
// app/dashboard/[id]/page.tsx
// 动态路由参数获取
interface Props {
params: { id: string }
searchParams: { [key: string]: string | string[] | undefined }
}

export default async function DashboardPage({ params, searchParams }: Props) {
// 注意：params 必须 await 才能用（Next.js 15 新特性）
const { id } = await params

// 如果是客户端组件，用 useParams()
// 'use client'
// const params = useParams()

return

Dashboard {id}

}
`

这个设计真的反人类：服务端组件里 params 变成 promise 了，我查了半小时文档才找到原因。官方文档这段文档不够清晰，说是"为了未来优化"，但至少给个迁移指南吧。

数据获取：别再用 getServerSideProps

还有个技巧：Next.js 15 彻底抛弃了 getServerSideProps 和 getStaticProps，改用 Server Components 直接 fetch。

`typescript
// app/posts/page.tsx
// 服务端组件直接 fetch，自动缓存和去重
async function getPosts() {
const res = await fetch('https://api.example.com/posts', {
// 缓存策略：强制缓存 1 小时
next: { revalidate: 3600 }
})

if (!res.ok) throw new Error('Failed to fetch')
return res.json()
}

export default async function PostsPage() {
const posts = await getPosts()

// 错误边界：用 error.tsx 处理
// 加载状态：用 loading.tsx 处理

return (

{posts.map(post => (

))}

)
}
`

为什么要这么写？因为 Server Components 默认运行在服务端，fetch 可以直接用缓存和 revalidation，客户端组件才需要 useEffect 或第三方库。性能对比：直接 fetch 从 3.2 秒降到 0.8 秒，因为服务端渲染+缓存。

性能优化：图片和字体

Next.js 15 对图片和字体做了重大改进。以前我手动优化图片，现在用 next/image 自动处理。

`tsx
// app/components/Image.tsx
import Image from 'next/image'
import { getPlaiceholder } from 'plaiceholder'

// 生成模糊占位图
async function getBlurData(src: string) {
const buffer = await fetch(src).then(r => r.arrayBuffer())
const { base64 } = await getPlaiceholder(Buffer.from(buffer))
return base64
}

export default async function OptimizedImage({ src, alt }: { src: string, alt: string }) {
const blurDataURL = await getBlurData(src)

return (
src={src}
alt={alt}
width={800}
height={600}
placeholder="blur"
blurDataURL={blurDataURL}
// 优先级：首屏图片设为 high
priority={false}
// 懒加载：自动优化
loading="lazy"
// 响应式：自动调整尺寸
sizes="(max-width: 768px) 100vw, 50vw"
className="rounded-lg"
/>
)
}
`

这个设计真的很实用：placeholder=”blur” 配合 plaiceholder 库，图片加载时显示模糊占位，体验提升明显。加载时间从 2.1 秒降到 0.4 秒，因为 Next.js 自动生成 WebP 格式。

部署：Vercel vs 自建服务器

最后说部署。我用 Vercel 部署过 10 多个项目，也和自建服务器对比过。

Vercel 优势：

  • 自动 HTTPS、CDN
  • 零配置部署
  • 环境变量管理

自建服务器：

  • 成本更低（Vercel Pro $20/月）
  • 自定义域名和资源

`bash

Vercel 部署命令

npm run build # 本地构建测试
vercel deploy # 一键部署

自建服务器（Node.js 环境）

npm run build
npm run start # 生产环境

或用 PM2 守护进程

pm2 start npm --name "my-app" -- start
`

我的建议：小型项目用 Vercel，大项目自建。Vercel 的免费版够用，但要注意带宽限制（100GB/月）。

总结一下，你可以立刻用的三个点

  • 环境配置：Node.js 必须 18.17+，用 create-next-app 加 –typescript –tailwind –eslint
  • 路由设计：App Router 用 params 必须 await，layout.tsx 可以嵌套，loading.tsx 自动处理加载状态
  • 性能优化：next/image 用 placeholder=”blur” 和 sizes，Server Components 直接 fetch` 缓存

    • 这些经验都是我在实际项目中踩过的坑，希望对你有帮助。如果遇到 Next.js 15 的新特性问题，欢迎在评论区交流。

    滚动至顶部