Checkpoint 4：Vercel 前端构建缺少 @x402/* 依赖

挑战地址：https://speedrunethereum.com/challenge/tokenization

本文是 Speedrun Ethereum Tokenization 系列第三篇，记录 Checkpoint 4 发布前端时的 Vercel 构建依赖问题。

隐私说明：本文不包含真实钱包地址、交易哈希、部署 URL、团队名、项目名或本地绝对路径。

系列目录

问题：Vercel 构建缺少 @x402/* 依赖

当前 Challenge 步骤：Checkpoint 4 - Ship

合约和 Mint 流程已经完成，现在正在使用 Vercel 发布前端，为最终提交挑战准备公开网址。

1. Vercel 命令

在项目根目录执行：

1
yarn vercel --prod

Vercel CLI 成功完成登录和项目链接：

1
Linked to your-team/your-project

也成功创建了一个 Production Deployment。部署 URL 和团队、项目信息在本文中省略。

但构建最后失败：

1
Error: Command "yarn run build" exited with 1

2. 查看 Vercel 构建日志

终端只显示构建失败，没有显示具体错误。

使用 Vercel CLI 查看完整日志：

1
2
3
./node_modules/.bin/vercel inspect \
  <DEPLOYMENT_URL> \
  --logs

关键错误如下：

1
2
3
4
5
Module not found: Can't resolve '@x402/core/client'
Module not found: Can't resolve '@x402/evm'
Module not found: Can't resolve '@x402/evm/exact/client'
Module not found: Can't resolve '@x402/evm/upto/client'
Module not found: Can't resolve '@x402/svm/exact/client'

因此这次 Vercel 失败不是 NFT 合约问题，也不是前端组件代码问题，而是依赖安装不完整。

3. 定位依赖链

缺失模块的依赖链如下：

1
2
3
4
5
6
7
@rainbow-me/rainbowkit
    -> @wagmi/connectors/baseAccount
    -> @base-org/account
    -> @coinbase/cdp-sdk
    -> @x402/core
    -> @x402/evm
    -> @x402/svm

项目根目录的 package.json 中有：

1
2
3
"resolutions": {
  "@coinbase/cdp-sdk": "1.52.0"
}

在当前安装结果中：

1
2
@base-org/account 2.4.0
    -> @coinbase/cdp-sdk 1.52.0

@coinbase/cdp-sdk@1.52.0 的内部代码会动态导入：

1
2
3
4
import("@x402/core/client")
import("@x402/evm/exact/client")
import("@x402/evm/upto/client")
import("@x402/svm/exact/client")

但是这些 @x402/* 包并没有被完整地声明和安装。

本地开发环境可能因为之前的 node_modules 残留而看不到问题；Vercel 每次都会执行全新的：

1
yarn install

所以缺失依赖会在 Vercel 构建时暴露出来。

4. 根因总结

1
2
3
4
5
6
Vercel 全新安装依赖
    -> @coinbase/cdp-sdk@1.52.0 被安装
    -> cdp-sdk 动态导入 @x402/*
    -> @x402/core、@x402/evm、@x402/svm 没有安装
    -> Turbopack 报告 Module not found
    -> yarn run build 退出码 1

这与合约、ERC-721、Mint 或 MetaMask 都没有关系。

5. 解决方案：显式安装缺失依赖

进入项目根目录：

1
cd "/path/to/challenge-tokenization"

执行：

1
2
3
4
yarn workspace @se-2/nextjs add \
  @x402/core@2.28.0 \
  @x402/evm@2.28.0 \
  @x402/svm@2.28.0

成功后，packages/nextjs/package.json 会新增：

1
2
3
"@x402/core": "2.28.0",
"@x402/evm": "2.28.0",
"@x402/svm": "2.28.0"

根目录 yarn.lock 也会对应增加这些包。

为什么选择 2.28.0：

  • 它包含 @x402/core/client
  • 它包含 @x402/evm/exact/client
  • 它包含 @x402/evm/upto/client
  • 它包含 @x402/svm/exact/client
  • 这些路径正好对应 cdp-sdk 的动态导入

安装后验证导入：

1
2
3
4
5
6
7
node --input-type=module -e '
await import("@x402/core/client");
await import("@x402/evm/exact/client");
await import("@x402/evm/upto/client");
await import("@x402/svm/exact/client");
console.log("all x402 imports succeeded");
'

预期输出：

1
all x402 imports succeeded

6. 在本地验证生产构建

不要直接重新部署，先运行与 Vercel 相同的生产构建：

1
yarn next:build

这次构建成功：

1
2
✓ Compiled successfully
✓ Generating static pages

构建过程中仍会看到一个非致命警告：

1
useScaffoldEventHistory is deprecated

这个警告不会导致构建失败，也不影响本次挑战提交。

7. 重新发布到 Vercel

本地构建通过后，再执行：

1
yarn vercel --prod

如果 Vercel 项目已经链接过，CLI 可能会直接进入部署。若再次询问项目设置，选择当前已经创建的：

1
your-project

部署完成后，Vercel 会给出 Production URL。将该网址提交到 Speedrun Ethereum 挑战页面即可。

8. 检查清单

发布前确认：

1
2
3
4
5
6
7
packages/nextjs/package.json 中有 @x402/core
packages/nextjs/package.json 中有 @x402/evm
packages/nextjs/package.json 中有 @x402/svm
yarn.lock 已更新
yarn next:build 本地成功
链上已经部署 YourCollectible
deployedContracts.ts 中已经包含 Sepolia 地址

然后执行：

1
yarn vercel --prod

返回索引

完整排错路线