Vercel部署因Chakra-UI自定义Recipe变体类型检查失败，原因何在？

问题情况 #

本地开发时，自定义Chakra UI按钮Recipe添加了error variant，执行npx @chakra-ui/cli typegen src/theme/index.ts更新类型后，IDE和yarn tsc都无类型错误，但Vercel部署时出现以下错误：

Type error: Type 'error' is not assignable to type 'ConditionalValue<"outline" | "solid" | "subtle" | "surface" | "ghost" | "plain" | undefined>'.

使用的依赖版本：

"@chakra-ui/react": "^3.25.0",
"@emotion/react": "^11.14.0",

自定义按钮Recipe代码片段：

export const buttonRecipe = defineRecipe({
  base: {
    // ...
  },
  variants: {
    variant: {
      // ...
      error: {
        borderWidth: '1px',
        borderColor: 'red.400',
        color: 'red.200',
        _hover: { borderColor: 'red.700', color: 'red.200', bg: 'red.950' }
      }
    },
    size: {
      // ...
    }
  }
});

原因分析 #

1. 类型生成文件未提交：typegen生成的自定义类型文件（如chakra-ui.d.ts）可能被.gitignore排除，本地有该文件所以类型校验通过，但Vercel部署环境没有，只能使用Chakra UI默认的按钮Variant类型集合。
2. 依赖版本不一致：^3.25.0的版本范围允许安装3.25.x的最新小版本，本地和Vercel安装的依赖版本可能存在差异，导致类型约束不一致。
3. 构建流程未执行typegen：本地手动执行了类型生成，但Vercel的构建脚本里没有包含该步骤，部署时无法生成包含自定义Variant的类型文件。

解决方案 #

• 提交类型生成文件：
  找到typegen生成的类型文件（通常在项目根目录或指定的src目录下），检查.gitignore是否忽略了它，若已忽略则移除对应规则，然后将文件提交到Git仓库。
• 锁定依赖版本：
  修改package.json中@chakra-ui/react的版本为固定版本3.25.0（去掉前缀^），确保本地和Vercel安装的依赖完全一致。
• 在构建脚本中加入typegen命令：
  更新package.json的scripts，在构建前先执行类型生成，示例（以Next.js为例）：

  "scripts": {
    "build": "npx @chakra-ui/cli typegen src/theme/index.ts && next build"
  }
  

  这样Vercel构建时会自动生成最新的自定义类型，再执行后续构建和类型检查。
• 清除Vercel缓存：
  登录Vercel控制台，进入项目的「设置」-「缓存」页面，手动清除构建缓存后重新触发部署，避免旧缓存导致的问题。

内容的提问来源于stack exchange，提问作者Phil Lucks