# 前端剧本 ## 你可能搞错了什么 **“我将使用‘纱链’。”** 错了。 “yarn chain”为您提供了一个空的本地链，没有协议、没有代币、没有状态。 “yarn fork --network base”为您提供了真实 Base 的副本，其中包括 Uniswap、Aave、USDC、真正的鲸鱼余额 - 一切。总是分叉。 **“我部署到 IPFS 并且它可以工作。”** CID 更改了吗？如果不是，则您部署了陈旧的输出。路线有用吗？如果没有 `trailingSlash: true`，除了 `/` 之外的每个路由都会返回 404。你检查过 OG 镜像吗？如果没有“NEXT_PUBLIC_PRODUCTION_URL”，它会指向“localhost:3000”。 **“我将手动设置项目。”** 不要。 `npx create-eth@latest` 处理一切 — Foundry、Next.js、RainbowKit、脚手架钩子。切勿运行 `forge init` 或从头开始创建 Next.js 项目。 ** ** ## 分叉模式设置 ### 为什么是分叉，而不是链纱线链（错误）纱线叉——网络底座（正确） └─ 空本地链 └─ Real Base 主网分叉 └─ 无协议 └─ Uniswap、Aave 等可用 └─ 无代币 └─ 真实的 USDC、WETH 存在 └─ 隔离测试 └─ 针对真实状态进行测试 ### 设置 npx create-eth@latest # 选择：铸造厂、目标链、名称 cd <项目名称> 纱线安装 yarn fork --network base # 终端 1：真实 Base 的分叉纱线部署＃终端2：将合同部署到分叉 yarn start # 终端 3：Next.js 前端 ### 关键：Chain ID 陷阱 **使用分叉模式时，前端目标网络必须是“chains.foundry”（链 ID 31337），而不是您要分叉的链。** 分叉在 Anvil 本地运行，链 ID 为 31337。即使您分叉 Base： // 开发期间的scaffold.config.ts targetNetworks: [chains.foundry], // ✅ 不是chains.base！仅在将合约部署到真实网络时才切换到“chains.base”。 ### 启用区块挖掘 # 在新终端中 — 依赖时间的逻辑需要铸造 rpc anvil_setIntervalMining 1 如果没有这个，“block.timestamp”将保持冻结状态。任何使用时间戳（截止日期、到期日、归属）的合约逻辑都会悄然中断。 **通过编辑 `packages/foundry/package.json` 将 `--block-time 1` 添加到 fork 脚本中，使其永久化**。 ** ** ## 部署到 IPFS（推荐） IPFS 是 SE2 的推荐部署路径。完全避免了 Vercel 的内存限制。生成一个完全分散的静态站点。 ### 完整构建命令 cd 包/nextjs rm -rf .next out # 始终先清理 NEXT_PUBLIC_PRODUCTION_URL="https://yourapp.yourname.eth.link" \ NODE_OPTIONS="--require ./polyfill-localstorage.cjs" \ NEXT_PUBLIC_IPFS_BUILD=true \ NEXT_PUBLIC_IGNORE_BUILD_ERROR=true \ 纱线结构 # 上传到BuidlGuidl IPFS 纱线 bgipfs 上传出 # 保存 CID！ ### 节点 25+ localStorage Polyfill（必需） Node.js 25+ 附带了一个内置的“localStorage”对象，该对象缺少标准 WebStorage API 方法（“getItem”、“setItem”）。这会破坏“next-themes”、RainbowKit 以及任何在静态页面生成期间调用“localStorage.getItem()”的库。 **您将看到的错误：** 类型错误：localStorage.getItem 不是函数预呈现页面“/_not-found”时发生错误 **修复：** 在 `packages/nextjs/` 中创建 `polyfill-localstorage.cjs`： if (typeof globalThis.localStorage !== "未定义" && typeof globalThis.localStorage.getItem !== "函数") { const store = new Map(); globalThis.localStorage = { getItem: (key) => store.get(key) ??空， setItem: (key, value) => store.set(key, String(value)), 删除项目：（键）=> store.delete（键），清除：() => store.clear(), key: (index) => [...store.keys()][index] ??空，获取长度() { 返回store.size; }, }; } **为什么`--require`而不是`instrumentation.ts`？** Next.js 生成一个单独的构建工作进程来进行预渲染。 `--require` 注入到每个节点进程（包括工作进程）。 `next.config.ts` polyfill 仅在主进程中运行。 `instrumentation.ts` 不在构建工作线程中运行。只有“--require”有效。 ### IPFS 路由 — 为什么路由中断 IPFS 网关提供静态文件。没有服务器处理路由。三件事必须是真的： **1.`output: "export"` in next.config.ts** — 生成静态 HTML 文件。 **2.`trailingSlash: true`（关键）** — 这是路由中断的第一大原因： * `trailingSlash: false` (默认) → 生成 `debug.html` * `trailingSlash: true` → 生成 `debug/index.html` * IPFS 网关自动将目录解析为“index.html”，但不是裸文件名 * 不带尾部斜杠： `/debug` → 404 ❌ * 尾随斜杠： `/debug` → `debug/` → `debug/index.html` ✅ **3\.页面必须在静态预渲染中幸存下来**——任何在“yarn build”（导入时的浏览器 API、localStorage）期间崩溃的页面都会被静默跳过 → IPFS 上的 404。 **完整的 IPFS 安全 next.config.ts 模式：** const isIpfs = process.env.NEXT_PUBLIC_IPFS_BUILD === "true"; 如果（isIpfs）{ nextConfig.output = "导出"; nextConfig.trailingSlash = true; nextConfig.images = { 未优化: true }; } **SE2 的区块浏览器页面** 在导入时使用“localStorage”，并在静态导出期间崩溃。如果不需要，请将“app/blockexplorer”重命名为“app/_blockexplorer-disabled”。 ### 过时构建检测 **#1 IPFS footgun：** 您编辑代码，然后部署旧版本。 # 任何代码更改后强制执行： rm -rf .next out # 1. 删除旧工件 # ... 运行完整的构建命令 ... # 2. 从头开始重建 grep -l "YOUR_STRING" out/_next/static/chunks/app/*.js # 3. 验证是否存在更改 # 时间戳检查： stat -f '%Sm' app/page.tsx # 源修改时间 stat -f '%Sm' out/ # 构建输出时间 # 来源比 out 更新/ = STALE BUILD。先重建！ **CID 就是证据：** 如果 IPFS CID 在部署后没有更改，则您部署了相同的内容。真正的代码更改总是会产生新的 CID。 ### 部署后验证路由 ls out/*/index.html # 每个路由都有一个目录+index.html curl -s -o /dev/null -w "%{http_code}" -L "https://GATEWAY/ipfs/CID/debug/" # 应该返回 200，而不是 404 ** ** ## 部署到 Vercel（替代方案） SE2 是一个 monorepo — Vercel 需要特殊配置。 ### 配置 1. **根目录：** `packages/nextjs` 2. **安装命令：** `cd ../.. && yarn install` 3. **构建命令：**保留默认值（`下一个构建`） 4. **输出目录：**保留默认值（`.next`） # 通过API：卷曲 -X 补丁“https://api.vercel.com/v9/projects/PROJECT_ID”\ -H“授权：持有者$VERCEL_TOKEN”\ -H“内容类型：application/json”\ -d '{"rootDirectory": "packages/nextjs", "installCommand": "cd ../.. && 纱线安装"}' ### 常见故障错误 |原因 |修复 ---|---|--- “未检测到 Next.js 版本”|未设置根目录 |设置为“packages/nextjs” “cd packages/nextjs：没有这样的文件”|构建命令有 `cd` |清除它 - 根目录处理这个 OOM/退出代码 129 | SE2 monorepo 超过 8GB |使用 IPFS 代替，或 `vercel --prebuilt` ### 决策树想要部署 SE2？ ├─ IPFS（推荐）→yarn ipfs / 手动构建+上传 │ └─ 完全去中心化，无内存限制，与ENS配合使用 ├─ Vercel → 设置 rootDirectory + installCommand │ └─ 快速 CDN，但集中化。大型项目可能出现 OOM └─ vercel --prebuilt → 本地构建，将工件推送到 Vercel └─ 两全其美：本地构建能力 + Vercel CDN ** ** ## ENS 子域设置两个主网事务将 ENS 子域指向您的 IPFS 部署。 ### 事务 1：创建子域（仅限新应用程序） 1. 打开“https://app.ens.domains/yourname.eth” 2. 转到“子名称”选项卡→“新子名称” 3. 输入标签（例如`myapp`）→下一步→跳过个人资料→打开钱包→确认 4. 如果gas卡住了：将MetaMask切换到以太坊→“活动”选项卡→“加速” ### 事务 2：设置 IPFS 内容哈希 1. 导航到“https://app.ens.domains/myapp.yourname.eth” 2.“记录”选项卡→“编辑记录”→“其他”选项卡 3. 粘贴到内容哈希字段：`ipfs://` 4. 保存→打开钱包→在MetaMask中确认对于现有应用程序的**更新**：跳过 Tx 1，仅执行 Tx 2。 ### 验证 # 1.链上内容哈希匹配 RESOLVER=$(强制调用 0x00000000000C2e074eC69A0dFb2997BA6C7d2e1e \ “解析器（bytes32）（地址）”$（cast namehash myapp.yourname.eth）\ --rpc-url https://eth.llamarpc.com) 强制转换调用 $RESOLVER "contenthash(bytes32)(bytes)" \ $(cast namehash myapp.yourname.eth) --rpc-url https://eth.llamarpc.com # 2. 网关响应（缓存可能需要 5-15 分钟） curl -s -o /dev/null -w "%{http_code}" -L "https://myapp.yourname.eth.link" # 3. OG元数据正确（不是本地主机）卷曲-s -L“https://myapp.yourname.eth.link”| grep 'og：图像' **使用`.eth.link`而不是`.eth.limo`** — `.eth.link`在移动设备上效果更好。 ** ** ## 进入生产 — 完整清单当用户说“发货”时，请严格遵循此顺序。 ### 第 1 步：最终代码审查 🤖 * 纳入所有反馈 * 没有重复的h1，没有原始地址，没有共享的isLoading * `scaffold.config.ts` 有 `rpcOverrides` 和 `pollingInterval: 3000` ### 第 2 步：选择域名👤 问：_“您想要什么子域？例如`myapp.yourname.eth`→`myapp.yourname.eth.link`”_ ### 步骤 3：生成 OG 图像 + 修复元数据🤖 * 创建 1200×630 PNG (`public/thumbnail.png`) — 不是普通的 SE2 缩略图 * 将“NEXT_PUBLIC_PRODUCTION_URL”设置为实时域 * 验证 `og:image` 将解析为绝对生产 URL ### 步骤 4：干净构建 + IPFS 部署 🤖 cd 包/nextjs && rm -rf .next out NEXT_PUBLIC_PRODUCTION_URL="https://myapp.yourname.eth.link" \ NODE_OPTIONS="--require ./polyfill-localstorage.cjs" \ NEXT_PUBLIC_IPFS_BUILD=true NEXT_PUBLIC_IGNORE_BUILD_ERROR=true \ 纱线结构 # 上传前验证： ls out/*/index.html # 路由存在 grep 'og:image' out/index.html # 不是本地主机 stat -f '%Sm' app/page.tsx # 比 out/ 更旧的源 stat -f '%Sm' 输出/ yarn bgipfs upload out # 保存CID ### 第 5 步：分享以获得批准👤 发送：_“构建已准备好进行审核：`https://community.bgipfs.com/ipfs/`”_ **在接触 ENS 之前等待批准。** ### 第 6 步：设置 ENS 🤖 创建子域（如果是新的）+设置 IPFS 内容哈希。两笔主网交易。 ### 第 7 步：验证🤖 * 内容哈希匹配链上 * `.eth.link` 网关响应 200 * OG图像正确加载 * 路由工作（`/debug/` 等） ### 第 8 步：报告 👤 _“住在`https://myapp.yourname.eth.link` - ENS 内容哈希在链上确认，展开元数据集。”_ ** ** ## 构建验证过程代码编译时，构建尚未完成。当您像真实用户一样对其进行测试后，就完成了。 ### 第 1 阶段：代码 QA（自动） * 扫描 `.tsx` 文件中的原始地址字符串（应使用 `

`） * 扫描多个按钮共享的“isLoading”状态 * 扫描交易按钮上缺失的“禁用”道具 * 验证 RPC 配置和轮询间隔 * 使用绝对 URL 验证 OG 元数据 * 验证任何文件中没有公共 RPC ### 第 2 阶段：智能合约测试 forge 测试 # 所有测试均通过 forge test --fuzz-runs 10000 # 模糊测试测试边缘情况：零金额、最大金额、未经授权的调用者、重入尝试。 ### 第 3 阶段：浏览器测试（真正的测试）打开应用程序并进行完整的演练： 1. **加载应用程序** — 它渲染正确吗？ 2. **检查页面标题** — 是否正确，不是“Scaffold-ETH 2”？ 3. **连接钱包** — 连接流程有效吗？ 4. **错误的网络** — 连接到错误的链上，验证是否出现“Switch to Base” 5. **切换网络** — 单击切换按钮，验证其是否有效 6. **批准流程** — 验证批准按钮显示，单击它，等待发送，验证操作按钮出现 7. **主要操作** — 单击主要操作，验证加载程序，等待 tx，验证状态更新 8. **错误处理** — 拒绝钱包中的交易，验证 UI 恢复 9. **地址显示** — 所有地址都显示 ENS/blockies，而不是原始十六进制？ 10. **分享 URL** — 检查 OG 展开（图像、标题、描述） ### 第 4 阶段：QA 子代理（复杂构建）对于更大的项目，生成一个具有新上下文的子代理。为其提供存储库路径和部署的 URL。它根据用户体验规则读取所有代码，打开浏览器，独立单击并报告问题。 ** ** ## 不要做这些 * ❌ `yarn chain` — 使用 `yarn fork --network ` * ❌ `forge init` — 使用 `npx create-eth@latest` * ❌ 手动 Next.js 设置 — SE2 处理它 * ❌ 手动钱包连接 — SE2 已预配置 RainbowKit * ❌ 编辑 `deployedContracts.ts` — 它由 `yarn deploy` 自动生成 * ❌ 在 `scaffold.config.ts` 中硬编码 API 密钥 — 使用 `.env.local` * ❌ 在生产中使用 `mainnet.base.org` — 使用 Alchemy 或类似的 ** ** ## 资源 * **SE2 文档：** * **UI 组件：** * **SpeedRun 以太坊：** * **ETH 技术树：** * **BuidlGuidl IPFS：**

前端剧本

包含技能