开发 Dapp 踩坑实录：RainbowKit + wagmi + Next.js 环境下的依赖大坑

最近在用 npm init @rainbow-me/rainbowkit@latest 快速搭建 Web3 Dapp 项目，遇到了一些依赖相关的坑，特此记录，供后来者参考。

1. 项目初始化

按照官方文档，直接用如下命令初始化项目：

1npm init @rainbow-me/rainbowkit@latest
2# 或者 pnpm create @rainbow-me/rainbowkit

一切看似顺利，依赖也都自动装好了。

2. 启动项目，遇到大坑

执行 pnpm dev 或 npm run dev，页面直接报错：

SyntaxError: The requested module '@vanilla-extract/sprinkles/createUtils' does not provide an export named 'createMapValueFn'

核心报错信息：

The requested module '@vanilla-extract/sprinkles/createUtils' does not provide an export named 'createMapValueFn'

3. 问题分析

这个报错的本质是：依赖版本不兼容。
RainbowKit 依赖的 @vanilla-extract/sprinkles 版本和实际安装的版本不一致，导致找不到 createMapValueFn 这个导出。
直接安装低版本（如 1.2.1）会发现根本没有这个版本，最新的只有 1.6.x。

4. 解决方法

4.1 清理依赖和缓存

先清理所有依赖和缓存，避免脏数据：

1rm -rf node_modules pnpm-lock.yaml
2pnpm store prune
3pnpm install

4.2 强制锁定依赖版本

在 package.json 里加上如下内容：

1"overrides": {
2  "@vanilla-extract/sprinkles": "1.6.3",
3  "@vanilla-extract/css": "1.16.0",
4  "@vanilla-extract/dynamic": "2.1.2"
5},
6"resolutions": {
7  "@vanilla-extract/sprinkles": "1.6.3",
8  "@vanilla-extract/css": "1.16.0",
9  "@vanilla-extract/dynamic": "2.1.2"
10}

注意：

overrides 是 pnpm/yarn/npm 8+ 支持的字段，用于强制覆盖依赖树中的包版本。
resolutions 是 yarn/pnpm 支持的字段，也能锁定依赖树中的包版本。
两个都写是为了最大兼容性，确保依赖树中所有相关包都用指定版本，避免依赖地狱。

4.3 重新安装依赖

1pnpm install

5. 其他常见疑问

5.1 projectId 是什么？

不是你的钱包地址！
是你在 cloud.reown.com 或 WalletConnect Cloud 等平台新建项目后获得的 Project ID。
用于钱包连接、Dapp 认证等。

alt text

5.2 wagmi 是什么？

wagmi 是一个专为 React/Web3 应用开发的前端库，简化钱包连接、合约交互、账户管理等操作。
搭配 RainbowKit 使用体验更佳。

6. 总结

Web3 前端开发，依赖地狱是常态，尤其是涉及 RainbowKit、wagmi、vanilla-extract 等多个生态时。
遇到依赖冲突，优先考虑用 overrides 和 resolutions 强制锁定版本。
多关注官方 issues 和社区讨论，很多坑大家都踩过。

7. 参考 package.json 示例

1{
2  "dependencies": {
3    "@rainbow-me/rainbowkit": "^2.2.8",
4    "@tanstack/react-query": "^5.55.3",
5    "next": "^15.3.3",
6    "react": "^19.1.0",
7    "react-dom": "^19.1.0",
8    "viem": "2.29.2",
9    "wagmi": "^2.15.6"
10  },
11  "devDependencies": {
12    "@types/node": "^20.14.8",
13    "@types/react": "^19.1.8",
14    "eslint-config-next": "^15.1.7",
15    "typescript": "5.5.4"
16  },
17  "overrides": {
18    "@vanilla-extract/sprinkles": "1.6.3",
19    "@vanilla-extract/css": "1.16.0",
20    "@vanilla-extract/dynamic": "2.1.2"
21  },
22  "resolutions": {
23    "@vanilla-extract/sprinkles": "1.6.3",
24    "@vanilla-extract/css": "1.16.0",
25    "@vanilla-extract/dynamic": "2.1.2"
26  }
27}

开发 Dapp 踩过的坑