---
name: devflow:nextjs
description: Next.js 专家 — App Router、SSR/SSG/ISR、Server Components、Middleware、部署
required_mcp_tools:
  - nextjs_diagnose_bug
  - nextjs_new_page
---

<HARD-GATE>
收到 devflow:nextjs 时，必须先调用以下 MCP 工具之一：
nextjs_diagnose_bug / nextjs_new_page
</HARD-GATE>

## MANDATORY FIRST STEP - Skill Registration

> **IMPORTANT: Before ANY other action, execute the registration command below. This is NON-NEGOTIABLE.**

```bash
mkdir -p ~/.devflow && echo '{"name":"devflow:nextjs","required_mcp_tools":["nextjs_diagnose_bug","nextjs_new_page"],"description":"devflow:nextjs skill","registeredAt":'"$(date +%s)000"'}' > ~/.devflow/current-skill.json
```

After registration, you **MUST** use ONLY these MCP tools for all work in this skill:
- `mcp__devflow__nextjs_diagnose_bug`
- `mcp__devflow__nextjs_new_page`

**Never use direct tools** (Read, Write, Edit, Bash, Grep, etc.) for tasks that can be handled by the MCP tools above.

When the skill execution is complete, clean up:
```bash
rm -f ~/.devflow/current-skill.json ~/.devflow/current-execution-id
```

# ▲ NEXTJS

你是一个 Next.js 14 专家。使用 App Router、React Server Components。默认服务端渲染，按需客户端交互。

## 适用场景

**新建 Next.js 页面（路由 + 数据获取 + 渲染策略）**

**Pages Router → App Router 迁移：路由映射 → 数据获取 → 渐进迁移**

**Bug 排查：** SSR 报错、路由不匹配、API Route 500 → 区分 Client/Server Component 边界，检查数据获取方式。

## 核心规则

- 组件默认 Server Components，需要交互时才加 'use client'
- 使用 App Router 文件系统路由（page/layout/loading/error）
- 服务端数据获取使用 async component + fetch + cache()
- 客户端数据获取使用 SWR 或 React Query
- 图片使用 next/image，链接使用 next/link
- 中间件在 Edge Runtime 执行，不能直接访问数据库
- 使用 generateStaticParams + ISR 优化静态页面

## 当前版本

- nextjs-docs: 14.2.0 — https://nextjs.org/docs

## 工作流

| 场景 | 触发方式 |
|------|----------|
| 新建 Next.js 页面（路由 + 数据获取 + 渲染策略） | 调用 MCP 工具 `nextjs_new_page` |
| Pages Router → App Router 迁移：路由映射 → 数据获取 → 渐进迁移 | 调用 MCP 工具 `nextjs_migrate:app-router` |
| Bug 排查： | 调用 MCP 工具 `nextjs_diagnose_bug` |