Web3 AI应用脚手架：基于Next.js与Wagmi的智能合约集成实践

1. 项目概述：一个为Web3应用注入AI灵魂的脚手架

如果你正在Web3领域创业，或者想快速验证一个结合了区块链与人工智能的创新想法，那么你大概率会遇到一个共同的难题：从零开始搭建一个完整的、现代化的Web3应用，其技术栈之复杂、集成点之多，足以让开发周期拉长到数月。你需要处理钱包连接、智能合约交互、链上数据获取、用户身份管理，现在还要加上AI模型的集成与调用。这就像要同时组装一辆汽车和一台电脑，零件散落一地，不知从何下手。

chainsy-net/web3-app-ai-template这个项目，就是为了解决这个痛点而生的。它不是一个简单的“Hello World”示例，而是一个生产就绪（Production-Ready）的全栈应用脚手架。其核心价值在于，它预先为你集成了2024年构建一个现代化Web3 AI应用所需的所有主流技术栈，并提供了清晰、模块化的代码结构。你可以把它理解为一个“乐高基础套装”，里面包含了搭建一座数字城堡所需的所有标准件和连接器，你只需要专注于设计城堡的独特外观和功能（即你的业务逻辑），而不用再去手工烧制每一块砖、锻造每一个齿轮。

这个模板主要面向两类开发者：一是希望快速启动项目的创业团队或独立开发者，能节省至少80%的初期基建时间；二是想要系统学习现代Web3全栈开发的进阶学习者，通过研究一个完整的、最佳实践的项目来理解各模块如何协同工作。它解决的问题非常具体：如何高效、优雅地将区块链的可验证性、去中心化资产与人工智能的智能推理、内容生成能力，融合在同一个用户体验流畅的Web应用中。

2. 技术栈深度解析：为什么是这些组合？

这个模板的技术选型堪称“豪华全家桶”，每一部分都经过深思熟虑，代表了当前（2024年）Web3和全栈开发领域的最优实践。理解为什么选择这些技术，比知道它们是什么更重要。

2.1 前端框架：Next.js 14 (App Router) + TypeScript + Tailwind CSS

Next.js 14 (App Router)是基石。在Web3应用中，页面性能、SEO（对于公开内容）和服务器端能力至关重要。Next.js的App Router提供了出色的服务端组件（RSC）支持。这意味着我们可以在服务器端安全地获取链下数据、处理环境变量，甚至预取一些链上数据（通过公共RPC），再将渲染好的页面发送给客户端。这避免了将敏感API密钥暴露给前端，也提升了首屏加载速度。对于需要实时交互的Web3操作（如签名交易），则使用客户端组件，做到了安全的职责分离。

TypeScript是大型应用和团队协作的“安全带”。Web3开发中，数据结构复杂（如交易对象、ABI类型），智能合约返回的数据类型必须精确。TypeScript能在编译期捕获大部分类型错误，比如确保你调用合约函数时传递了正确类型和数量的参数，这能极大减少生产环境下的运行时错误。

Tailwind CSS解决了样式开发的效率问题。其效用优先（Utility-First）的理念，允许开发者直接在JSX中快速构建响应式、高度定制化的UI，而无需在多个CSS文件间跳转。对于需要快速迭代UI的创业项目来说，这能节省大量时间。

2.2 Web3核心：Wagmi + Viem + RainbowKit

这是模板的“区块链连接层”，也是精髓所在。

Wagmi(We Are All Gonna Make It) 是一套完整的React Hooks集合，用于处理以太坊及其他EVM兼容链的交互。它抽象了连接钱包、读取链上状态、发送交易等复杂操作，提供了一套声明式、类似React Query的API。例如，用useAccount获取用户账户，用useBalance读取余额，用useContractWrite发送交易。它管理了连接状态、链切换、缓存等所有脏活累活。

Viem是一个轻量级、类型安全的以太坊TypeScript接口库。Wagmi在底层就使用了Viem。你可以把Viem看作是“axios for Ethereum”，但它更强大。它提供了对ABI的顶级类型安全支持，当你导入一个合约ABI后，它能自动生成所有函数和事件的类型，实现完美的智能提示和类型检查。在模板中，Viem被用于配置链（Chains）和创建公共客户端（Public Client）或钱包客户端（Wallet Client）。

RainbowKit是钱包连接按钮的“瑞士军刀”。它提供了一个美观、易用的按钮组件，集成了Rainbow、MetaMask、Coinbase Wallet、WalletConnect等数十种主流钱包。它自动处理钱包发现、连接、切换网络、显示错误信息等，并提供了一套可定制的主题系统。使用它，你可以在几分钟内拥有一个专业级的钱包连接界面，而不用自己处理各种钱包SDK的兼容性问题。

注意：虽然模板可能默认配置了以太坊主网和测试网，但在实际项目中，你需要根据目标用户群体调整支持的链。例如，如果面向普通用户，可能需优先支持Arbitrum、Polygon等Layer2；如果面向资深DeFi用户，则需加入Optimism、Base等。

2.3 AI集成：多种模式与API路由

这是模板的“智能大脑”部分。AI的集成方式多样，模板通常会提供几种最常用的模式。

1. 服务器端AI调用 (Next.js API Routes)：这是最安全、最推荐的方式。在/app/api/目录下创建路由，在服务器端环境使用OpenAI、Anthropic (Claude)、或开源的本地模型（通过Ollama等）的SDK。这样，你的API密钥完全不会暴露给浏览器。前端通过fetch或axios调用这些API路由。模板可能会提供一个/api/chat的示例，演示如何处理流式响应（Streaming），实现类似ChatGPT的打字机效果。

2. 客户端AI调用 (谨慎使用)：对于一些对安全性要求不高、或使用无需密钥的公共服务（如某些开放的模型API），也可以直接在客户端调用。模板可能会使用@ai-sdk/react这样的库来简化状态管理。但务必注意，任何嵌入前端代码的API密钥都是公开的，可能导致密钥被盗用和产生巨额费用。

3. 智能合约与AI的结合点：这是Web3 AI应用的创新所在。一种常见模式是“AI生成，链上存证”。例如： * 用户通过前端与AI对话，生成一段故事或一幅画的描述（Prompt）。 * 前端将AI生成的内容（或其哈希）与用户的数字签名一起，通过智能合约（可能是一个NFT铸造合约）上链。 * 合约记录下“某个地址在某个时间基于某个AI Prompt生成了某个内容”，实现创作过程的去中心化存证和所有权确认。 * 模板的智能合约部分会提供这样的基础合约示例。

2.4 状态管理与数据获取：Zustand + TanStack Query

Zustand是一个轻量级、不可变的状态管理库。相比于Redux，它API更简单，无需繁琐的Provider包裹和Action/Reducer定义。在模板中，它非常适合管理一些全局的、非服务器的应用状态，比如一个全局的侧边栏开关状态、主题模式（深色/浅色），或者是一个跨组件共享的、从链上或AI API获取后需要缓存的数据。

TanStack Query (原名React Query)是管理异步数据（服务器状态）的王者。在Web3 AI应用中，异步数据无处不在：从智能合约读取的数据、从AI API获取的回复、从IPFS获取的元数据。TanStack Query自动为你处理缓存、后台刷新、依赖更新、分页、错误重试等复杂逻辑。例如，你可以用一个useQuery来获取用户的NFT列表，它会自动缓存，当用户切换账户时自动失效并重新获取，你无需手动管理useState和useEffect。

2.5 基础设施：环境变量、代码质量与部署

模板会使用.env.local文件管理环境变量，严格区分公开变量和秘密变量（如NEXT_PUBLIC_前缀）。它会集成ESLint和Prettier来强制代码风格一致，并可能包含Husky预提交钩子，在提交代码前自动运行检查和格式化。

部署通常瞄准Vercel，因为其对Next.js的支持是无缝的。模板的配置会确保在Vercel上能正确识别服务端和客户端环境变量。对于智能合约部分，可能会集成Hardhat或Foundry进行开发、测试和部署，并可能包含示例脚本，将合约部署到测试网。

3. 项目结构与核心模块实操指南

让我们打开模板的源代码目录，像解构一台精密仪器一样，看看每个部件是如何安装和工作的。

3.1 目录结构全景

一个典型的、组织良好的模板目录结构如下：

web3-app-ai-template/ ├── app/ # Next.js 14 App Router 核心目录 │ ├── api/ # API 路由（安全调用AI的地方） │ │ └── chat/ # 示例：AI聊天接口 │ ├── globals.css # 全局样式（Tailwind导入点） │ ├── layout.tsx # 根布局，包含Providers │ └── page.tsx # 应用首页 ├── components/ # 可复用的React组件 │ ├── ui/ # 基础UI组件（按钮、卡片等） │ ├── web3/ # Web3专用组件（连接按钮、余额显示等） │ └── ai/ # AI交互组件（聊天框、提示词输入等） ├── contracts/ # 智能合约源码（Solidity/Vyper） │ ├── src/ # 合约文件 │ ├── test/ # 合约测试 │ └── scripts/ # 部署脚本 ├── hooks/ # 自定义React Hooks │ ├── useReadContract.ts # 封装合约读操作 │ └── useWriteContract.ts# 封装合约写操作 ├── lib/ # 工具函数和核心配置 │ ├── web3.ts # Wagmi & Viem 客户端配置 │ ├── ai.ts # AI SDK 初始化配置 │ └── constants.ts # 合约地址、ABI等常量 ├── public/ # 静态资源 ├── styles/ # 额外的样式文件 ├── .env.example # 环境变量示例文件 ├── next.config.js # Next.js 配置 ├── tailwind.config.ts # Tailwind CSS 配置 ├── tsconfig.json # TypeScript 配置 └── package.json

3.2 核心配置详解：lib/web3.ts

这是Web3连接的“总控室”。让我们深入看看它的典型配置：

// lib/web3.ts import { createConfig, http } from 'wagmi'; import { mainnet, sepolia, polygon } from 'wagmi/chains'; import { injected, walletConnect, coinbaseWallet } from 'wagmi/connectors'; import { getDefaultConfig } from '@rainbow-me/rainbowkit'; // 1. 定义项目支持的区块链网络 const projectId = process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID; // 从WalletConnect Cloud获取 if (!projectId) { console.warn('NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID is not set. WalletConnect may not work.'); } export const config = getDefaultConfig({ appName: 'My Web3 AI App', projectId: projectId || 'YOUR_PROJECT_ID', // 用于WalletConnect chains: [mainnet, sepolia, polygon], // 支持的网络 transports: { [mainnet.id]: http('https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY'), [sepolia.id]: http('https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY'), [polygon.id]: http('https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY'), }, ssr: true, // 启用服务端渲染支持 }); // 2. 创建Wagmi配置（RainbowKit的getDefaultConfig内部已处理，此示例展示原始方式） // export const config = createConfig({ // chains: [mainnet, sepolia], // connectors: [ // injected(), // walletConnect({ projectId }), // coinbaseWallet({ appName: 'My App' }), // ], // transports: { // [mainnet.id]: http(), // [sepolia.id]: http(), // }, // });

关键点解析：

• transports：这里配置了每个网络对应的RPC提供商节点。强烈建议使用Alchemy、Infura等专业节点服务，而不是公共RPC。公共RPC有速率限制且不稳定，在发送交易或频繁读取时极易失败。将你的服务API密钥放在服务器端环境变量中，并通过一个自定义的API路由转发请求，是更安全的生产环境做法。
• ssr: true：这对Next.js服务端组件兼容性至关重要。它确保Wagmi的上下文能在服务端被正确初始化，避免 hydration 不匹配错误。
• projectId：WalletConnect v2 必须的项目ID，需要在 WalletConnect Cloud 免费注册获取。这是连接众多钱包App（如MetaMask Mobile）的桥梁。

3.3 智能合约集成：从ABI到类型安全调用

模板通常会包含一个示例合约，比如一个简单的“AI内容存证”合约。集成步骤是标准化的：

第一步：编译合约，获取ABI。使用 Hardhat 或 Foundry 编译后，ABI 文件通常位于artifacts/contracts/MyContract.sol/MyContract.json。

第二步：将ABI和部署地址放入lib/constants.ts。

// lib/constants.ts import MyContractABI from '../artifacts/contracts/MyContract.sol/MyContract.json'; export const MY_CONTRACT_ADDRESS = { [mainnet.id]: '0x...', [sepolia.id]: '0x1234...', // 你的测试网部署地址 } as const; export const MY_CONTRACT_ABI = MyContractABI.abi;

第三步：创建类型安全的Hook进行调用。模板可能会在hooks/目录下提供封装好的Hook，或者你可以在组件中直接使用Wagmi的Hook。

// hooks/useMyContract.ts import { useReadContract, useWriteContract, useAccount } from 'wagmi'; import { MY_CONTRACT_ADDRESS, MY_CONTRACT_ABI } from '@/lib/constants'; import { sepolia } from 'wagmi/chains'; export function useRecordContent() { const { chain } = useAccount(); const { writeContract, isPending, error } = useWriteContract(); const record = (contentHash: string, prompt: string) => { if (!chain) return; writeContract({ address: MY_CONTRACT_ADDRESS[chain.id] || MY_CONTRACT_ADDRESS[sepolia.id], // 降级到测试网 abi: MY_CONTRACT_ABI, functionName: 'recordContent', args: [contentHash, prompt], }); }; return { record, isPending, error }; } // 在组件中使用 import { useRecordContent } from '@/hooks/useMyContract'; // ... 在事件处理函数中调用 record(hash, prompt)

第四步：读取合约数据。

// 在组件中直接读取 import { useReadContract } from 'wagmi'; const { data: totalRecords } = useReadContract({ address: MY_CONTRACT_ADDRESS[sepolia.id], abi: MY_CONTRACT_ABI, functionName: 'getTotalRecords', chainId: sepolia.id, });

实操心得：将合约交互封装成自定义Hook是极佳实践。它实现了逻辑与UI的分离，使组件更简洁，且Hook可以在多个组件中复用。务必在Hook内部处理链ID判断和降级逻辑，提升用户体验。

3.4 AI API路由实现：安全与流式响应

让我们看看app/api/chat/route.ts如何安全地调用OpenAI API并返回流式响应：

// app/api/chat/route.ts import { OpenAIStream, StreamingTextResponse } from 'ai'; // 使用 `ai` SDK 处理流 import OpenAI from 'openai'; // 强制此路由在服务器端运行，避免API密钥泄露 export const runtime = 'edge'; // 或 'nodejs'，取决于你的部署环境和模型支持 const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY!, // 从服务器环境变量读取 }); export async function POST(req: Request) { try { const { messages } = await req.json(); // 从前端获取消息历史 // 调用OpenAI API，开启流式输出 const response = await openai.chat.completions.create({ model: 'gpt-4o-mini', // 或 'gpt-4', 'gpt-3.5-turbo' stream: true, // 关键：启用流式传输 messages, temperature: 0.7, max_tokens: 1000, }); // 将OpenAI的流转换为标准的文本流 const stream = OpenAIStream(response); // 返回流式响应给前端 return new StreamingTextResponse(stream); } catch (error) { console.error('Error calling OpenAI API:', error); return new Response(JSON.stringify({ error: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' }, }); } }

前端调用示例：

// 在组件中使用 `useChat` 来自 `ai-sdk/react` import { useChat } from '@ai-sdk/react'; export function ChatComponent() { const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({ api: '/api/chat', // 指向我们的API路由 // onFinish 等回调函数... }); return ( <div> {/* 渲染消息列表 messages */} <form onSubmit={handleSubmit}> <input value={input} onChange={handleInputChange} disabled={isLoading} /> <button type="submit">Send</button> </form> </div> ); }

重要提示：runtime = 'edge'使用Vercel的边缘函数，冷启动更快，适合简单的AI调用。但如果你的AI处理逻辑复杂、依赖Node.js原生模块，或者使用某些仅支持Node.js的SDK（如LangChain的某些部分），则应使用runtime = 'nodejs'。务必在Vercel项目设置中配置好对应的环境变量OPENAI_API_KEY。

4. 从模板到真实应用：关键改造步骤与避坑指南

拿到模板只是第一步，将其改造成你自己的应用，还需要完成以下几个关键步骤，这里充满了“踩坑点”。

4.1 环境变量配置：安全第一

模板会提供一个.env.example文件。你的第一步就是复制它并填写自己的密钥。

# .env.local - 切勿提交到Git！ # Web3 NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=你的walletconnect项目id # 注意：RPC URL如果包含密钥，不建议用 NEXT_PUBLIC_ 前缀，应通过API路由代理 # NEXT_PUBLIC_ALCHEMY_ID=你的alchemy主网key (谨慎，会暴露) # AI OPENAI_API_KEY=sk-你的openai密钥 # ANTHROPIC_API_KEY=你的claude密钥 # 合约部署私钥（用于脚本，非前端） DEPLOYER_PRIVATE_KEY=你的私钥

避坑指南1：RPC密钥的前端暴露问题直接将包含密钥的RPC URL（如https://eth-mainnet.g.alchemy.com/v2/your-secret-key）放在NEXT_PUBLIC_变量中是高危行为。任何人查看页面源码都能拿到这个密钥，可能被滥用导致你的服务额度耗尽。正确做法是：

1. 在Vercel等平台设置服务器端环境变量ALCHEMY_MAINNET_KEY。
2. 在Next.js中创建一个API路由（如/api/rpc-proxy），在该路由中使用服务器端环境变量构造RPC请求，并转发客户端的请求。这样密钥永远不会离开服务器。

4.2 智能合约开发、测试与部署

模板中的合约示例通常很简单。你需要根据业务逻辑重写合约。

开发流程：

1. 编写合约：在contracts/src/下创建你的Solidity合约文件。
2. 编写测试：在contracts/test/下用JavaScript/TypeScript或Solidity（Foundry）编写全面测试。测试应覆盖正常功能和边界情况。对于涉及AI输入输出的合约，尤其要测试字符串长度、哈希值验证等。
3. 配置网络：在hardhat.config.ts中配置测试网（如Sepolia）的RPC URL和账户私钥（通过环境变量注入）。
4. 部署脚本：编写scripts/deploy.ts，使用ethers或viem部署合约，并可以自动验证源码（在Etherscan上）。

// scripts/deploy.ts 示例 (使用 Hardhat 和 ethers) import { ethers } from "hardhat"; async function main() { const MyContract = await ethers.getContractFactory("MyAIContract"); const contract = await MyContract.deploy(); await contract.waitForDeployment(); const address = await contract.getAddress(); console.log(`MyAIContract deployed to: ${address}`); // 可选：自动验证合约 // 需要安装 hardhat-etherscan 插件并配置 ETHERSCAN_API_KEY // await hre.run("verify:verify", { address: address }); } main().catch((error) => { console.error(error); process.exitCode = 1; });

部署命令：

# 编译 npx hardhat compile # 运行测试 npx hardhat test # 部署到Sepolia测试网 npx hardhat run scripts/deploy.ts --network sepolia

避坑指南2：Gas费估算与用户体验在用户执行链上交易（如存证）前，前端应使用useEstimateGas(Wagmi) 预估Gas费并显示给用户。对于新用户，他们可能没有测试网ETH。模板应考虑：

• 提供一个“水龙头”链接指引，让用户获取测试网代币。
• 对于主网应用，设计清晰的上链成本提示。复杂的AI计算+链上存证可能Gas费不菲。

4.3 前端功能模块开发与集成

这是将合约和AI能力与用户界面连接起来的部分。

1. 钱包连接与状态管理：模板已通过RainbowKit提供了连接按钮。你需要在整个应用中合理使用Wagmi的Hook来获取账户状态。

import { useAccount, useDisconnect } from 'wagmi'; function UserProfile() { const { address, isConnected } = useAccount(); const { disconnect } = useDisconnect(); if (!isConnected) return <p>请连接钱包</p>; return ( <div> <p>已连接: {address?.slice(0,6)}...{address?.slice(-4)}</p> <button onClick={() => disconnect()}>断开连接</button> </div> ); }

2. AI交互界面设计：结合@ai-sdk/react或类似库，构建聊天界面、提示词输入框、生成结果展示区。考虑加入生成状态指示器（如加载动画）、错误处理提示和重新生成按钮。

3. 链上存证流程串联：这是核心业务逻辑。流程如下：

// 伪代码，展示逻辑流 async function handleGenerateAndRecord() { // 1. 调用AI API生成内容 setIsAiLoading(true); const aiResult = await callAIApi(userPrompt); setIsAiLoading(false); // 2. 计算生成内容的哈希（例如使用SHA-256） const contentHash = await computeHash(aiResult); // 3. 调用智能合约，将哈希和原始Prompt上链存证 setIsContractPending(true); const { record } = useRecordContent(); await record(contentHash, userPrompt); // 这会触发钱包签名 setIsContractPending(false); // 4. 显示交易哈希，并提供区块链浏览器链接 showTransactionLink(txHash); }

避坑指南3：交易状态反馈与错误处理Web3交易充满不确定性（用户拒绝、网络拥堵、Gas不足）。必须提供清晰的反馈：

• 使用isPending状态显示“交易确认中...”。
• 监听交易回执 (useWaitForTransactionReceipt)，在确认后显示成功提示。
• 捕获错误并用用户友好的语言展示（如“用户拒绝了签名”、“网络繁忙，请稍后重试”）。

4.4 样式定制与主题适配

模板使用Tailwind CSS，定制主题非常方便。修改tailwind.config.ts：

// tailwind.config.ts import type { Config } from 'tailwindcss'; const config: Config = { content: ['./app/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'], theme: { extend: { colors: { brand: { primary: '#3B82F6', // 你的品牌蓝色 accent: '#10B981', // 你的品牌绿色 }, }, fontFamily: { sans: ['Inter var', 'sans-serif'], // 自定义字体 }, }, }, plugins: [], }; export default config;

然后，在app/globals.css中引入自定义样式，并确保在app/layout.tsx中应用了主题Provider（如果使用了next-themes等库来实现深色模式）。

5. 部署上线与生产环境优化

当本地开发测试完成后，部署到生产环境是临门一脚。

5.1 Vercel部署（推荐）

1. 推送代码：将代码推送到GitHub、GitLab或Bitbucket仓库。
2. 导入项目：在Vercel控制台，点击“New Project”，导入你的仓库。
3. 配置环境变量：在项目设置的“Environment Variables”页面，将你在.env.local中配置的所有非NEXT_PUBLIC_的变量（如OPENAI_API_KEY,ALCHEMY_MAINNET_KEY）添加进去。NEXT_PUBLIC_变量也可以在构建时在这里设置。
4. 部署：Vercel会自动检测为Next.js项目并开始部署。部署成功后，你会获得一个*.vercel.app的域名。

生产环境检查清单：

• [ ]环境变量：确保所有敏感密钥都已正确配置在Vercel中，未泄露在前端代码里。
• [ ]合约地址：确认前端constants.ts中配置的是已部署的生产环境合约地址，而不是测试网地址。
• [ ]RPC节点：生产环境务必使用付费层级的节点服务（如Alchemy Growth Tier），保证稳定性和速率。
• [ ]错误监控：集成Sentry或类似服务，监控前端和边缘函数/Serverless函数的错误。
• [ ]域名与SSL：绑定自定义域名，Vercel会自动提供SSL证书。

5.2 智能合约的正式部署与验证

1. 选择主网：根据你的应用场景，选择以太坊主网，或更便宜的Layer2（如Arbitrum, Optimism, Base, Polygon）。
2. 准备主网私钥：在Vercel环境变量或安全的CI/CD环境中设置DEPLOYER_PRIVATE_KEY。
3. 执行部署：运行部署脚本，指定主网网络。

   npx hardhat run scripts/deploy.ts --network mainnet

4. 验证合约源码：在Etherscan或对应链的区块浏览器上验证合约源码。这能建立用户信任，并允许他们直接在浏览器中读取合约。使用hardhat-etherscan插件可以自动化这一步。
5. 多链部署：如果你的用户可能分布在多条链上，需要考虑使用跨链部署工具或手动部署到多条链，并在前端动态切换合约地址。

5.3 性能与安全优化

性能优化：

• 图片优化：使用Next.js的<Image>组件自动优化图片。
• 字体优化：使用next/font本地加载字体，避免布局偏移。
• 代码分割：利用Next.js基于路由的自动代码分割。对于大型第三方库，考虑动态导入 (dynamic import)。
• 缓存策略：合理配置Wagmi和TanStack Query的缓存时间，减少不必要的RPC调用和API请求。

安全加固：

• API路由限流：对/api/chat等公开API路由实施限流，防止滥用。可以使用@upstash/ratelimit等Vercel兼容的服务。
• 输入验证与清理：在API路由和智能合约中，对所有用户输入进行严格的验证和清理，防止注入攻击。
• 依赖项更新：定期运行npm audit和npm update，保持所有依赖项为最新安全版本。

6. 常见问题排查与调试技巧

在实际开发中，你一定会遇到各种问题。这里记录一些典型问题的排查思路。

6.1 钱包连接相关问题

6.2 合约调用失败问题

6.3 AI API相关问题

6.4 通用调试技巧

1. 充分利用浏览器开发者工具：

   • Console：查看前端错误和日志。
   • Network：查看所有网络请求（前端API调用、RPC调用），检查请求参数和响应状态。
   • React Developer Tools：检查组件的Props和State，特别是Wagmi和TanStack Query提供的状态。

2. 查看服务器/边缘函数日志：

   • 在Vercel的部署控制台查看函数日志，这是诊断API路由错误的最直接方式。

3. 使用测试网和测试币：

   • 在开发阶段，绝对不要在主网上测试。充分使用Sepolia、Goerli（已弃用，转向Sepolia）、Polygon Mumbai等测试网，并从水龙头获取测试币。

4. 从简单到复杂：

   • 先确保钱包连接、基础合约读取等简单功能正常工作，再逐步添加AI集成、复杂交易等逻辑。分模块调试，缩小问题范围。

这个模板的价值，在于它提供了一个坚实、现代且经过验证的起点。它帮你扫清了基建的障碍，让你能集中所有火力去攻克业务逻辑和创新点这个真正的堡垒。当你按照上述步骤，一步步完成环境配置、合约开发、功能集成和部署上线后，你收获的不仅仅是一个可运行的应用，更是一套应对未来更多Web3 AI项目的成熟工程方法和实战经验。