技能使用指南

frontend-playbook（以太坊DApp前端部署指南）Skill 是什么？如何下载安装？

详解以太坊DApp前端部署指南Skill：一键启用即可获得从分支模式、IPFS 构建上传、Vercel 配置到 ENS 子域名绑定的完整发布清单，帮你避开路由 404、过时构建与时间戳冻结等高频坑点。含安装步骤、使用指南、竞品对比与常见问题，开发者快速上手必读。

以太坊DApp前端部署指南Skillfrontend-playbook
8 个章节 约 17 分钟阅读 AI 智能生成

以太坊DApp前端部署指南Skill：从本地分支链到 IPFS + ENS 的去中心化上线全流程

  • 它不是又一份"部署教程"，而是一套带检查清单的发布流程：从分支模式启动、静态构建、IPFS 上传，到 ENS 子域名绑定与上线后验证，每一步都有明确命令和判定标准。
  • 最容易踩的坑被提前拦下：yarn chain 空链陷阱、trailingSlash 导致的路由 404、Node 25+ 的 localStorage 崩溃、IPFS 部署了过时构建（CID 没变）等高频事故，技能里都给了对照解法。
  • 两条部署路径可选：IPFS（推荐，完全去中心化、避开内存限制）与 Vercel（快速 CDN，但需要处理单体仓库配置），技能给出决策树帮你选。
  • “构建成功"不等于"能上线”：技能内置四阶段验证流程，包括代码质量扫描、合约测试、浏览器真实点击演练和独立审查子代理。
  • 适合谁：正在用或准备用 Scaffold-ETH 2 发布 dApp 的开发者、需要给用户一个可访问 .eth.link 域名的团队，以及想避免"上线即翻车"的前端+DApp 全栈工程师。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

技能中文名：以太坊DApp前端部署指南Skill 技能英文名：frontend-playbook 技能ID：13698 技能内部名称：前端部署手册

这个技能要解决的问题非常具体：把"我的 dApp 在本地跑起来了"变成"任何人都能通过一个域名打开它"。绝大多数以太坊前端项目卡在最后一公里——本地 yarn start 一切正常，一旦要发布就出现路由 404、OG 图片指向 localhost:3000、合约时间戳冻结导致逻辑失效、ENS 内容哈希指向旧版本等问题。该技能基于 Scaffold-ETH 2 沉淀，但同时声明适用于任何以太坊前端项目，把"构建到生产"的完整流程、检查清单和反模式清单打包成一个可随时调用的技能。

安装思路与步骤（一键安装 AI 技能提升开发效率的通用路径）：

  1. 确认安装前提：你需要在支持"技能（Skill）"机制的 AI 编程助手或技能市场环境中使用；同时准备好一个待部署的以太坊前端项目（若是新项目，技能建议用 npx create-eth@latest 从零生成，而不是手工搭 Next.js）。
  2. 找到技能入口：在技能库 / 技能市场 / 技能管理面板中，用技能ID 13698 或英文名 frontend-playbook 检索并添加该技能。具体检索入口与按钮名称以官方说明为准。
  3. 启用技能：添加后确认该技能处于"已启用 / 已挂载"状态，使其在当前会话中可被调用（不同平台的启用方式略有差异，以官方说明为准）。
  4. 验证是否生效：向助手提出一个该技能领域内的问题，例如"部署到 IPFS 之前我要检查哪些东西？“或"为什么我的 /debug 路由在 IPFS 上返回 404？”。如果回答中出现 trailingSlash: true、output: "export"、CID 校验、NEXT_PUBLIC_PRODUCTION_URL 等该技能特有的概念与检查项，说明技能已正常生效。
  5. 正式使用：直接说"帮我把这个项目发布到生产"，技能会按照其内置的八步生产检查清单推进。

该技能的主要功能和特点

  • 分支模式（Fork Mode）配置指导：明确区分 yarn chain（空本地链，无协议、无代币、无状态）与 yarn fork --network base（真实 Base 主网副本，含 Uniswap、Aave、USDC 与真实余额），并给出创建-安装-分支-部署-启动的完整命令序列。
  • 链 ID 陷阱纠偏：指出分支模式下前端目标网络必须是 chains.foundry（链 ID 31337），而不是所分支的链，只有真正部署到真实网络时才切换到目标链配置。
  • 区块挖掘设置：提醒必须通过 cast rpc anvil_setIntervalMining 1（或在分支脚本中加入 --block-time 1）启用出块，否则 block.timestamp 冻结，任何依赖时间戳的合约逻辑（截止时间、过期、归属）会静默失效。
  • IPFS 全量构建方案：给出包含清理、环境变量、Node 25+ localStorage 填充、yarn build 与 yarn bgipfs upload out 的完整命令，并解释为何 --require 注入方式优于 instrumentation.ts 与 next.config.ts 填充。
  • 路由正确性保障：解释 output: "export" 与 trailingSlash: true 的必要性——没有尾部斜杠，除 / 外每个路由都会 404，并提示静态预渲染崩溃的页面会被静默跳过。
  • 过时构建检测机制：提供删除 .next/out、用 grep 校验改动是否进入产物、用 stat 比对源文件与产物时间戳的方法，并给出"CID 未变即代表部署了旧内容"的判据。
  • Vercel 部署的替代路径与失败对照表：针对单体仓库给出根目录、安装命令等配置，并把"未检测到 Next.js 版本"“cd 无此文件”"OOM / 退出码 129"三类失败映射到原因与修复方案，附决策树。
  • ENS 子域名全流程：两笔主网交易（创建子名、设置 ipfs://<CID> 内容哈希），更新已有应用只需第二笔；并提供基于 cast 的链上内容哈希校验、网关状态码检查与 OG 元数据检查。
  • 八步生产检查清单 + 四阶段构建验证：从代码审查、域名确认、OG 图片生成、清洁构建、分享待批、ENS 设置、验证到最终报告；验证阶段覆盖自动化扫描、forge test 与 10000 次模糊测试、十项浏览器真实点击演练。
  • "不要做这些"反模式清单：把 yarn chain、forge init、手工 Next.js 配置、手写钱包连接、直接编辑自动生成的 deployedContracts.ts、在配置里硬编码 API 密钥、生产环境使用公共 RPC 等隐性错误集中列出。

和普通"问一句答一句"的通用助手相比，它的差异在于：它不解释概念，而是给判定标准（CID 是否变化、路由是否返回 200、og:image 是否还是 localhost），因此结论可验证、可复现。

如何使用该技能？

步骤 1：确认项目基座 新项目直接让技能走 npx create-eth@latest（选择 foundry、目标链、项目名），随后 yarn install。已有项目则直接进入部署流程。技能明确反对使用 forge init 或手工创建 Next.js 项目。

步骤 2：以分支模式启动本地环境 开三个终端分别执行：

yarn fork --network base   # 终端 1：真实 Base 分支
yarn deploy                # 终端 2：部署合约到分支
yarn start                 # 终端 3：启动 Next.js 前端

同时把 scaffold.config.ts 中的 targetNetworks 设为 chains.foundry，并启用出块。

步骤 3：提出发布请求 典型输入示例：“帮我把这个项目发布到生产，子域名用 myapp.myname.eth。” 技能会先反问确认域名（例如 myapp.yourname.eth → myapp.yourname.eth.link），再进入构建。

步骤 4：执行清洁构建

cd packages/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 \
  yarn build

构建前需准备 1200×630 的 public/thumbnail.png 作为 OG 图片，而不是沿用 Scaffold-ETH 2 默认缩略图。

步骤 5：上传前自检 ls out/*/index.html 确认每个路由都有目录与 index 文件；grep 'og:image' out/index.html 确认不是 localhost；stat 比对源文件与产物时间戳，确认不是过时构建。随后 yarn bgipfs upload out 上传并记录 CID。

步骤 6：分享待批 把 https://community.bgipfs.com/ipfs/<CID> 发给相关方审查，技能明确要求在接触 ENS 之前等待批准。

步骤 7：绑定 ENS 在 app.ens.domains 创建子名（新应用）、在"记录 → 编辑记录 → 其他"中填入 ipfs://<CID>（新旧应用都需要），共两笔主网交易。

步骤 8：上线后验证 用 cast 查询解析器与链上 contenthash 是否与 CID 一致；用 curl 检查 .eth.link 网关返回 200；检查 OG 图片为绝对生产地址；逐个访问 /debug/ 等子路由。技能特别提示使用 .eth.link 而非 .eth.limo，因为移动端表现更好，并提示网关缓存可能需要 5–15 分钟。

输出说明：最终你会得到一份包含"已上线地址 + 链上内容哈希已确认 + 元数据设置完成"的发布报告，以及可复用的检查记录。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
以太坊DApp前端部署指南Skill（frontend-playbook） 面向以太坊前端的端到端发布流程技能 分支模式配置、IPFS 构建与上传、Vercel 配置、ENS 子域名、八步检查清单、四阶段验证 在技能市场检索技能ID 13698 或英文名启用即可；需具备基础命令行能力 用 Scaffold-ETH 2 或其他以太坊前端框架做正式发布 优势：把隐性坑点显性化为可判定检查项，流程可复现；不足：不代跑命令，ENS 步骤仍需人手动签两笔交易
官方框架文档自行摸索 参考文档 概念说明与零散示例 零安装，但需要自行串联全流程 学习与查漏补缺 优势：权威、覆盖面广；不足：缺少"发布前必须逐项确认"的强约束，容易遗漏路由与 OG 配置
通用 AI 编程助手（无专用技能） 泛用型问答与代码生成 代码补全、报错解释 低门槛 临时问题排查 优势：灵活；不足：回答依赖上下文，缺少固定清单，容易给出"能跑就行"的模糊结论
IPFS 托管 / 静态托管平台 托管服务 静态站点上链与域名加速 需要自行准备符合静态导出要求的构建产物 只解决"托管"这一段 优势：开箱即用；不足：不负责构建配置、路由、ENS 与验证，构建不正确时照样 404
Vercel 直接部署 中心化 CDN 托管 自动构建与全球加速 需处理单体仓库的根目录与安装命令 追求访问速度、可接受中心化的项目 优势：CDN 快；不足：大型单体仓库可能内存溢出（退出码 129），需退回本地预构建方案

该技能的典型应用场景与实际体验情况

场景一：独立开发者首次把 dApp 发布上线。 角色是个人开发者，痛点是不清楚"IPFS + ENS"到底需要几步、卡在哪。使用方式是让技能按八步清单推进。实际体验：上手难度低，因为每一步都有可执行命令和"看到什么才算成功"的判据；但要注意 ENS 的创建子名与设置内容哈希是两笔独立主网交易，第一次操作容易漏掉第二笔。

场景二：团队项目上线前的质量把关。 角色是技术负责人，痛点是自己 review 容易疲劳漏项。使用方式是让技能跑阶段一自动化扫描（原始地址字符串、共享 isLoading、缺失 disabled、RPC 与轮询配置、OG 绝对 URL）加十项浏览器演练。实际体验：效果明显，尤其是"拒绝钱包交易后 UI 是否恢复""错误链上是否出现切换网络按钮"这类必须真实点击才能发现的问题；建议把浏览器演练固定为发布前必过项。

场景三：老项目更新版本。 角色是维护者，痛点是"改了代码，用户看到的还是旧版"。使用方式是每次改动后清空 .next 与 out 重新构建，并用 CID 是否变化作为"确实换了内容"的证据；ENS 更新时跳过创建子名、只改内容哈希。实际体验：这是该技能最立竿见影的部分，"CID 未变即部署了旧产物"这条判据能省下大量排查时间。

场景四：本地逻辑"莫名不生效"的排查。 角色是合约前端联调者，痛点是用 yarn chain 起了空链，或时间戳冻结导致截止时间、归属逻辑永远不触发。使用方式是切换到 yarn fork --network base 并启用区块挖掘。实际体验：需要注意链 ID 必须写成 chains.foundry（31337），否则前端连不上；这是新手最容易反复踩的一条。

该技能能为用户带来的价值

效率层面：把原本需要在多个文档间来回跳转的发布流程压缩成一条可执行序列，从构建、上传、ENS 到验证形成闭环；清洁构建、上传前自检、上线后验证三段式检查，把"上线后才发现 404"的返工成本前移到发布之前。

质量与门槛层面：把 trailingSlash、localStorage 填充、链 ID、区块挖掘这些"不查文档就会踩、踩了还很难定位"的隐性知识固化成清单，显著降低 DApp 前端发布的心智负担；即使不熟悉 Scaffold-ETH 2 内部机制，也能借助判定标准（CID 变化、状态码 200、OG 不是 localhost）独立确认结果正确。

长期价值：产出的是可复用的发布流程与验证习惯，而不是一次性的救命回答；对团队而言，同一套清单可以被不同成员反复执行，发布质量不再依赖"谁更熟练"。

常见问题 FAQ

Q1：怎么安装这个技能？收费吗？ 在支持技能机制的环境中，用技能ID 13698 或英文名 frontend-playbook 在技能库检索并启用即可，具体入口与计费方式以官方说明为准。需要提醒的是：技能本身不产生链上费用，但绑定 ENS 子域名与设置内容哈希涉及两笔主网交易，你需要自行承担 gas；IPFS 上传则使用技能中提到的 BuidlGuidl IPFS 上传通道，其额度政策以官方说明为准。

Q2：我 Solidy 写得不熟，能直接用吗？ 可以。该技能聚焦"前端部署到生产"这一段，核心是构建配置、路由、元数据、托管与域名绑定；合约侧它只要求你跑通 forge test 与模糊测试并覆盖零金额、最大金额、未授权调用者、重入等边界情况。但如果合约本身逻辑有问题，部署流程再规范也救不了，建议先把合约测试做扎实。

Q3：为什么我在 IPFS 上除了首页全是 404？ 最常见的两个原因：一是没有开启 trailingSlash: true，导致生成的是 debug.html 而不是 debug/index.html，而 IPFS 网关只会把目录解析到 index.html；二是某个页面在静态预渲染阶段崩溃（例如导入时调用了浏览器 API 或 localStorage），被静默跳过，产物里根本没有这个页面。前者改配置，后者修崩溃点或临时禁用该路由。

Q4：应该选 IPFS 还是 Vercel？ 技能给出的倾向是：追求完全去中心化、希望与 ENS 域名配合、且项目体积较大时选 IPFS，可避开内存限制；需要快速 CDN 且可接受中心化时选 Vercel，但务必把根目录设为 packages/nextjs、安装命令设为 cd ../.. && yarn install，否则会出现"未检测到 Next.js 版本"；若两者都想要，可考虑本地预构建后推送产物的方案。

Q5：绑定 ENS 后多久能访问？ 链上记录确认后，网关还存在缓存，技能提示可能需要 5–15 分钟。验证时建议三件事一起做：用 cast 查询链上 contenthash 是否与你的 CID 一致、用 curl 检查 .eth.link 返回 200、确认 og:image 是生产绝对地址而不是 localhost:3000。另外推荐使用 .eth.link 而不是 .eth.limo，移动端体验更好。