使用Vite+Vue3+TypeScript构建组件库发布npm后类型声明丢失怎么解决？

核心问题排查 #

你的配置存在4个关键错误：

• 错误使用@rollup/plugin-typescript生成类型：该插件无法解析.vue单文件组件的类型，就算配置正确也无法生成完整的组件类型定义
• package.json未声明类型入口：TS找不到你的包对应的类型文件
• vue-tsc参数错误：原构建命令加了--noEmit参数，不会输出任何生成文件
• 路径配置错误：vite.config.ts和tsconfig.json中的rootDir配置非法，导致路径解析失败

修复步骤 #

1. 清理无效配置 #

删除vite.config.ts中@rollup/plugin-typescript相关的所有配置，修改后的vite.config.ts参考：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),
    },
  },
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.ts'),
      name: 'celestia-vue',
      fileName: (format) => `celestia-vue.${format}.js`
    },
    rollupOptions: {
      external: ['vue'],
      output: {
        sourcemap: false,
        globals: {
          vue: 'Vue'
        }
      }
    }
  }
})

2. 修正tsconfig.json配置 #

调整编译选项，确保类型声明输出到dist目录：

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "lib": [
      "es6",
      "esnext",
      "es2016",
      "dom",
      "dom.iterable",
      "scripthost"
    ],
    "allowJs": true,
    "declaration": true,
    "declarationDir": "./dist/types", // 类型声明输出目录
    "emitDeclarationOnly": true, // 只生成声明文件，不生成JS
    "sourceMap": false,
    "outDir": "dist",
    "rootDir": "./src", // 源码根目录
    "importHelpers": true,
    "strict": true,
    "noImplicitAny": true,
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "types": [
      "webpack-env",
      "jest"
    ],
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ],
  "exclude": [
    "node_modules",
    "dist",
    "tests"
  ]
}

3. 修正package.json配置 #

添加类型入口，修改构建命令：

{
  ...
  "files": [
    "dist"
  ],
  "main": "./dist/celestia-vue.umd.js",
  "module": "./dist/celestia-vue.es.js",
  "types": "./dist/types/index.d.ts", // 新增：类型声明入口
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts", // 新增：导出对应的类型
      "import": "./dist/celestia-vue.es.js",
      "require": "./dist/celestia-vue.umd.js"
    }
  },
  "unpkg": "./dist/celestia-vue.umd.js",
  "jsdelivr": "./dist/celestia-vue.umd.js",
  "scripts": {
    "vite:dev": "vite",
    "serve": "vue-cli-service serve",
    "vite:serve": "vite preview",
    "build": "vue-cli-service build",
    // 修正构建命令：先构建代码，再生成类型声明，最后替换别名路径
    "vite:build": "vite build && vue-tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
    "test:unit": "vue-cli-service test:unit",
    "lint": "vue-cli-service lint"
  },
  ...
}

注意：如果你的项目使用了@路径别名，需要安装tsc-alias依赖处理生成的声明文件中的别名路径，执行npm i tsc-alias -D安装即可。如果没有使用别名，可以去掉命令中&& tsc-alias -p tsconfig.json部分。

4. 验证效果 #

执行npm run vite:build，检查dist目录下是否生成了types文件夹，且存在index.d.ts文件。本地测试可以使用npm link将包链接到其他项目，验证类型引入是否正常。

内容的提问来源于stack exchange，提问作者Micheal J. Roberts