使用Vite构建React TS库时.d.ts声明文件丢失问题

核心问题分析 #

你的构建命令tsc -b && vite build存在执行逻辑冲突：

1. 先执行tsc -b会基于tsconfig.app.json的配置生成声明文件到dist目录
2. 随后vite build默认会清空整个dist目录，再生成js/css文件
3. 虽然vite-plugin-dts会在vite构建过程中尝试生成声明，但tsconfig与插件的重复声明配置，会导致最终类型文件被清理

解决方案 #

方案一：用vite-plugin-dts全权处理声明生成（推荐） #

这种方式避免tsc和插件的配置冲突，简化构建流程：

1. 修改tsconfig.app.json，禁用tsc的文件输出能力：

{
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true, // 关键：禁止tsc输出任何文件
    "jsx": "react-jsx",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true,

    // 移除以下声明相关配置：
    // "declaration": true,
    // "declarationMap": true,
    // "emitDeclarationOnly": true,
    // "outDir": "dist",
  },
  "include": ["src"]
}

2. 修改package.json的build命令，去掉tsc -b：

{
  "scripts": {
    "build": "vite build"
  }
}

3. 优化vite-plugin-dts配置，确保生成合并后的单文件声明：

dts({
  entryRoot: 'src',
  outDir: 'dist',
  rollupTypes: true, // 将所有类型合并为单个main.d.ts
})

方案二：保留tsc生成声明，调整执行顺序 #

如果需要继续用tsc生成声明，需避免vite清空dist：

1. 修改build命令顺序，让vite先构建，再用tsc生成声明：

{
  "scripts": {
    "build": "vite build && tsc -b"
  }
}

2. 在vite.config.js中禁用dist目录清空：

export default defineConfig({
  // ... 其他配置
  build: {
    emptyOutDir: false, // 禁止vite清空dist目录
    // ... 原有lib和rollupOptions配置
  }
})

验证结果 #

执行npm run build后，dist目录应包含：

• main.js：库的核心代码
• main.css：注入的样式
• main.d.ts：包含SomeComponent和useSomeHook的完整类型定义

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