Next.js + TypeScript项目部署Vercel时chessboard-element组件出现TypeScript类型错误

我之前也碰到过这种本地运行完全正常，但一部署到Vercel就触发TypeScript类型报错的情况，大概率是类型声明识别或者项目配置的问题，咱们一步步来排查解决：

1. 确认自定义元素类型声明的正确性 #

你已经创建了src/types/chessboard.d.ts，但要确保它正确扩展了JSX的固有元素类型，这样TypeScript才能识别<chess-board>标签。把你的类型声明文件改成下面这样：

// src/types/chessboard.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    // 定义chess-board标签的属性，包含你用到的所有props
    'chess-board': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
      position?: string;
      'draggable-pieces'?: boolean;
      // 如果还有其他用到的属性（比如orientation），也可以在这里补充
    };
  }
}

// 全局声明chess-board元素的类型，方便useRef调用组件方法
declare global {
  interface HTMLElementTagNameMap {
    'chess-board': ChessBoardElement;
  }
}

interface ChessBoardElement extends HTMLElement {
  // 这里添加chess-board元素的方法，比如设置位置、获取位置等
  setPosition: (position: string) => void;
  getPosition: () => string;
}

export {};

2. 检查tsconfig.json的配置 #

确保TypeScript能正确找到你的自定义类型文件，修改tsconfig.json的相关配置项：

{
  "compilerOptions": {
    // 保留你原有的其他配置
    "typeRoots": ["./node_modules/@types", "./src/types"], // 告诉TS去这些目录查找类型声明
    "jsx": "preserve" // Next.js 14版本使用这个配置即可
  },
  "include": ["src/**/*", "src/types/**/*"], // 确保包含你的自定义类型文件
  "exclude": ["node_modules"]
}

3. 处理Vercel的缓存问题 #

有时候Vercel会缓存旧的构建信息，导致新的类型声明没被加载。你可以：

• 打开Vercel控制台找到你的项目，进入「Deployments」页面，选择最新的部署记录，点击「Redeploy」，然后取消勾选「Use existing build cache?」，强制触发全新构建。
• 或者在package.json的build命令前增加清理步骤，避免旧缓存干扰：

  "scripts": {
    "build": "rm -rf .next && next build",
    // 保留其他原有脚本
  }
  

4. 确认客户端组件配置无误 #

你已经在ChessBoard.tsx顶部添加了"use client"，这一步是对的——因为自定义元素只能在客户端渲染，只要这个组件没有被服务器组件直接错误引用（比如page.tsx作为服务器组件引用ChessBoard是没问题的，Next.js会自动处理客户端组件的渲染），这部分就不会有问题。

5. 统一TypeScript版本 #

有时候本地和Vercel使用的TypeScript版本不一致，也会导致类型校验逻辑出现差异。在package.json里明确指定TypeScript的版本，避免自动升级到不兼容版本：

"devDependencies": {
  "typescript": "^5.2.2",
  // 保留其他原有依赖
}

按照上面的步骤操作后，重新部署到Vercel应该就能解决这个类型错误了。

备注：内容来源于stack exchange，提问作者david-oruna