自研TypeScript库跨文件导入类型在项目中无法自动补全问题

我开发了一个包含输入、容器等基础组件的自研UI库，以第三方依赖的方式引入到项目中使用。遇到的问题是：

• 在项目中使用该库时，从库内其他文件导入的类型无法触发自动补全；但如果把类型定义在导出组件的同一文件中，自动补全就能正常工作。
• 这类跨文件的类型在库内部可以正常解析，但打包后在项目里无法被识别。

正常触发自动补全的写法：

interface IInputProps { ...... }

const Input = ({ inputProps }: IInputProps) => .....

库内部正常，但项目中无法自动补全的写法：

import { IInputProps } from './Types'

const Input = ({ inputProps }: IInputProps) => ....

tsconfig.json 配置 #

{
  "compilerOptions": {
    "baseUrl": "src",
    "lib": ["dom", "dom.iterable", "esnext", "es5"],
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": false,
    "jsx": "react-jsx",
    "outDir": "dist/library",
    "sourceMap": true,
    "declaration": true,
    "strictNullChecks": true,
    "noImplicitAny": false,
    "downlevelIteration": true,
    "types": ["node", "lodash", "jest", "sortablejs"],
    "typeRoots": [
      "src/typings/*.d.ts",
      "node_modules/@types",
      "node_modules/ui-lib/src/typings/*.d.ts",
      "node_modules/jest-canvas-mock/types/index.ts"
    ]
  },
  "include": [
    "src/**/*",
    "src/mylib-ui/typings/*.d.ts",
    "node_modules/ui-library/**/*.d.ts"
  ],
  "exclude": ["src/**/*.spec.*", "src/**/*.md", "dist"]
}

webpack 配置片段 #

{
  test: /\.(ts|js)x?$/i, 
  include: [srcPath, uiLibraryPath], 
  use: [
    'babel-loader', // javascript files loader
    {
      loader: 'ts-loader', // typescript loader
      options: {
        allowTsInNodeModules: true,
        transpileOnly: true, 
      },
    },
  ],
}

1. 确认类型声明文件生成情况 #

你的tsconfig.json已经开启了declaration: true，但需要检查：

• 跨文件类型（如./Types.ts中的IInputProps）对应的.d.ts文件是否被生成到dist/library目录下。
• 确保include配置覆盖了所有类型文件，src/**/*默认会包含src下所有文件，若类型文件在特殊路径需单独添加。

2. 修复ts-loader的类型生成配置 #

transpileOnly: true会让ts-loader只做代码转译，跳过类型声明生成，有两种修复方式：

• 方案一：关闭transpileOnly
  修改webpack中ts-loader的配置：

  {
    loader: 'ts-loader',
    options: {
      allowTsInNodeModules: true,
      transpileOnly: false, // 关闭后ts-loader会生成类型声明
    },
  }
  

• 方案二：保留transpileOnly并添加插件（推荐，提升构建速度）
  安装fork-ts-checker-webpack-plugin：

  npm install fork-ts-checker-webpack-plugin --save-dev
  

  在webpack配置中引入并配置：

  const ForkTsCheckerWebpackPlugin = require('fork-ts-checker-webpack-plugin');
  
  module.exports = {
    // ...其他配置
    plugins: [
      new ForkTsCheckerWebpackPlugin({
        typescript: {
          configFile: './tsconfig.json',
          declaration: true, // 强制生成类型声明文件
        },
      }),
    ],
  };
  

3. 配置package.json的类型入口 #

在库的package.json中添加types字段，指定主类型声明文件路径，示例：

{
  "main": "dist/library/index.js",
  "types": "dist/library/index.d.ts",
  // ...其他字段（如name、version等）
}

如果是多组件库，也可以指定类型目录："types": "dist/library/types"，确保所有.d.ts文件都在该目录下。

4. 检查类型的导出与导入 #

确保类型文件中的接口/类型是导出状态：

// ./Types.ts
export interface IInputProps { ...... }

组件文件中正确导入后，组件本身也要导出：

// Input.tsx
import { IInputProps } from './Types';

export const Input = ({ inputProps }: IInputProps) => {
  // ...组件逻辑
};

5. 清理缓存并重新构建 #

• 删除库的dist目录，重新执行构建命令。
• 在使用该库的项目中，重启IDE或清空node_modules/.cache，确保类型缓存被更新。

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