为何Rollup无法解析.d.ts文件？tsc正常但Rollup报错求助

Hey there, this is a super common gotcha when working with TypeScript definitions and bundlers like Rollup—let’s break down the key reasons this might be happening and how to fix them:

1. Your .d.ts isn’t a proper module (it’s global) #

If your type definition file doesn’t have any export or import statements, TypeScript treats it as a global declaration file, not a module. tsc will pick up the types just fine during type checking, but Rollup will throw a resolution error because you’re trying to import something that isn’t actually a module.

Fix:

• If it’s meant to be a module (you need to import its types), add a dummy export to turn it into a module:

  // your-file.d.ts
  export interface MyType { /* ... */ }
  // Or an empty export if it's augmenting existing types:
  export {};
  

• If it’s a global type (meant to be available everywhere), remove the import statement from your .ts file and make sure the file is included in your tsconfig.json’s include array.

2. You’re missing a corresponding JavaScript implementation #

.d.ts files only describe types—they don’t contain actual executable code. tsc ignores this because it only checks types, but Rollup needs to bundle real code. If you’re importing from a path that only has a .d.ts file (no .ts/.js file), Rollup will fail to find the actual module.

Fix:

• If the module is supposed to have code, add a corresponding .js/.ts file (even an empty one with export {} if it’s just types for now).
• If you’re only importing types, use TypeScript’s type-only import syntax so Rollup knows to ignore it during bundling:

  import type { MyType } from './your-types';
  

3. Rollup plugin order is wrong #

Rollup executes plugins in the order they’re listed, and this can break module resolution if you have the wrong sequence. rollup-plugin-typescript2 needs to process your TypeScript files first before node-resolve or commonjs try to resolve imports.

Fix:
Reorder your plugins so typescript() comes first:

// rollup.config.js
import typescript from 'rollup-plugin-typescript2';
import resolve from 'rollup-plugin-node-resolve';
import commonjs from 'rollup-plugin-commonjs';

export default {
  // ... other config
  plugins: [
    typescript(), // Process TS first
    resolve(),    // Then resolve modules
    commonjs()    // Handle CommonJS modules
  ]
};

4. Path mappings in tsconfig aren’t mirrored in Rollup #

If you’re using baseUrl or paths in your tsconfig.json to shorten import paths, tsc will resolve them correctly, but Rollup won’t unless you tell it about those mappings.

Fix:

• Use @rollup/plugin-alias to replicate your tsconfig path mappings:

  // rollup.config.js
  import alias from '@rollup/plugin-alias';
  
  export default {
    plugins: [
      alias({
        entries: [
          { find: '@types', replacement: './src/types' } // Match your tsconfig paths
        ]
      }),
      typescript(),
      resolve(),
      commonjs()
    ]
  };
  

• Alternatively, double-check that rollup-plugin-typescript2 is using your tsconfig properly (it should pick up paths by default, but adjust tsconfigOverride if needed).

5. Rollup isn’t including your .d.ts files #

If your .d.ts file isn’t in the include array of your tsconfig.json, or if rollup-plugin-typescript2 is excluding it, Rollup might not recognize it as part of your project.

Fix:

• Update your tsconfig.json to include the file:

  {
    "include": ["src/**/*", "./path/to/your-file.d.ts"]
  }
  

• Check the include option in your rollup-plugin-typescript2 config to ensure it’s not filtering out the file.

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