OpenClaw 的 Next.js Expert 技能

OpenClaw Next.js Expert 技能概述

Next.js Expert 技能为你的 OpenClaw 智能体提供对 Next.js 框架的深入了解——涵盖 App Router、React Server Components、Server Actions、中间件、缓存策略以及生产部署模式。无需翻阅文档或搜索 Stack Overflow，直接向 OpenClaw 提问，即可获得针对你项目的准确、最新的指导。

该技能非常适合使用 Next.js 13+ 构建现代全栈 React 应用的开发者。无论你是从 Pages Router 迁移、实现复杂的数据获取模式，还是优化应用性能，OpenClaw Next.js Expert 技能都能提供基于当前最佳实践的上下文感知回答。

典型工作流程：

1. 向 OpenClaw 提出 Next.js 架构问题或描述你遇到的问题。
2. 智能体利用其对 Next.js 约定和模式的知识来分析你的问题。
3. 你将收到包含代码示例、文件结构建议以及相关 Next.js 文档 链接的详细解答——无需切换标签页。

Next.js Expert 技能安装前的准备

在安装 Next.js Expert 技能之前，请确保你已具备以下条件：

• 已安装并运行 OpenClaw（v1.0+）
• 已安装 Node.js 18.17+ — 下载 Node.js
• 拥有一个 Next.js 项目（推荐 13+ 版本以使用 App Router 功能）
• 已安装 clawhub CLI 用于技能管理

验证你的环境：

# 检查 OpenClaw 版本
openclaw --version

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

# 检查是否有 Next.js 项目
npx next --version

如何安装 Next.js Expert 技能

使用一条命令即可安装 Next.js Expert 技能：

npx clawhub@latest install nextjs-expert

验证安装结果：

clawhub list

你应该能在已安装技能列表中看到 nextjs-expert。你也可以在安装前使用 clawhub inspect nextjs-expert 查看技能详情。

Next.js Expert 技能配置指南

Next.js Expert 技能是一个基于知识的技能，不需要 API 密钥或外部服务认证。安装后即可直接使用。

可选的项目上下文

为了获得最佳效果，请确保你的 OpenClaw 智能体能够访问你的项目目录。该技能可以分析你现有的代码，从而提供更有针对性的建议：

# 进入你的 Next.js 项目根目录
cd /path/to/your-nextjs-app

# 在项目目录中启动 OpenClaw
openclaw

当 OpenClaw 能够访问你的 next.config.js、tsconfig.json 和 app/ 目录结构时，Next.js Expert 技能可以提供与你特定配置相匹配的建议——包括你的路由结构、中间件配置和已安装的依赖包。

保持更新

该技能涵盖从 Next.js 13 到最新版本的内容。要确保你获得最新的指导：

# 将技能更新到最新版本
npx clawhub@latest install nextjs-expert

Next.js Expert 技能使用示例

1. App Router 架构决策

你："我的仪表盘部分应该使用 layout 还是 template？我需要侧边栏保持不变，但主内容区域在导航时重新渲染。"

智能体会解释 layout.tsx（跨导航持久化，保持状态）和 template.tsx（每次导航时重新创建）之间的区别，然后建议使用 layout 来实现侧边栏，并确认主内容区域会自动重新渲染，因为每个页面都是独立的路由段。

2. 数据获取策略

你："我需要获取每 5 分钟更新一次的产品数据。在 App Router 中最好的方法是什么？"

智能体会建议在 Server Component 中使用带有基于时间的重新验证的 fetch，并提供完整示例：

// app/products/page.tsx
async function getProducts() {
  const res = await fetch('https://api.example.com/products', {
    next: { revalidate: 300 } // 每 5 分钟重新验证
  });
  return res.json();
}

它还会解释何时使用 revalidatePath 或 revalidateTag 通过 Server Actions 进行按需重新验证。

3. Server Components 与 Client Components

你："我有一个产品页面，包含静态描述和一个交互式的'加入购物车'按钮。我应该如何拆分组件？"

智能体会建议将产品页面保持为 Server Component 以优化 SEO 和性能，仅将 AddToCartButton 提取为使用 'use client' 的 Client Component。它会解释其中的好处：产品描述 HTML 在服务器端渲染，无需客户端 JavaScript，而交互按钮则独立进行水合。

4. 中间件与认证

你："如何使用认证中间件保护 /dashboard 下的所有路由？"

智能体会提供使用 matcher 配置的中间件实现，展示如何检查会话令牌，并解释重定向模式。它还会指出中间件在 Edge 运行时中运行，无法使用 fs 等 Node.js API，并推荐使用 NextAuth.js 或 Clerk 集成模式来实现生产环境的认证方案。

安全与最佳实践

在使用 AI 辅助构建 Next.js 应用时，请遵循以下准则：

• 仔细审查生成的代码。 在将代码建议添加到项目之前，务必阅读并理解。该技能提供的是指导，而非保证可用于生产环境的代码。
• 验证 Server Actions 的输入。 当技能建议使用 Server Actions 进行表单处理时，请确保添加适当的输入验证和权限检查——智能体会提醒你，但请务必自行验证。
• 将敏感数据保留在服务器端。 切勿在 Client Components 中暴露 API 密钥、数据库凭据或密钥。仅对真正公开的值使用 NEXT_PUBLIC_ 前缀的环境变量。
• 使用 TypeScript 确保类型安全。 该技能默认提供 TypeScript 示例。利用类型检查及早发现错误，尤其是在复杂的数据获取模式中。
• 遵循最小权限原则。 当技能建议 API 路由处理器或中间件模式时，确保它们只暴露所需的最少数据和访问权限。

常见错误与故障排除

"You're importing a component that needs useState. It only works in a Client Component."

你在 Server Component 中使用了 React Hook（useState、useEffect、useContext 等）。在文件顶部添加 'use client' 指令，或将交互部分提取到单独的 Client Component 中。

// 在文件最顶部添加此指令
'use client';

import { useState } from 'react';

"Error: Dynamic server usage: Route /api/... couldn't be rendered statically"

某个路由使用了动态功能（cookies、headers、searchParams），但 Next.js 正在尝试对其进行静态生成。你可以在路由中添加 export const dynamic = 'force-dynamic'，或者重构代码以避免在可静态渲染的页面中使用动态 API。

// 强制该路由使用动态渲染
export const dynamic = 'force-dynamic';

"Module not found: Can't resolve 'fs' in middleware"

你正在中间件或 Edge 路由中使用仅限 Node.js 的模块。中间件运行在 Edge Runtime 中，不支持 fs、path 或其他 Node.js 内置模块。请将文件系统相关逻辑移至使用 export const runtime = 'nodejs' 的 API 路由中。