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 路由中。