TypeScript移除HTML导入，如何保留供Rollup/Webpack后续处理？

我之前也碰到过类似的坑——TypeScript会把这种仅通过.d.ts声明的资源导入判定为「无实际值的类型导入」，编译时直接删掉，导致后续打包工具拿不到导入路径。咱们可以从这几个关键地方调整：

1. 修正.d.ts的模块声明方式 #

首先要让TypeScript知道，.html模块是有实际导出值的，而不是空的类型声明。把你的HTML模块声明改成这样：

// html.d.ts
declare module '*.html' {
  // 声明导出的HTML内容为字符串（对应webpack/html-loader的输出）
  const content: string;
  export default content;
}

如果你的打包工具是把HTML导出为其他格式（比如模板函数），可以把content的类型改成对应类型就行，核心是必须有具体的导出值声明，不能只写declare module '*.html';这种空声明。

2. 调整tsconfig.json的编译选项 #

在compilerOptions里加上两个关键配置，强制TypeScript保留资源导入：

{
  "compilerOptions": {
    // 用ES模块语法，适配Rollup/Webpack的打包逻辑
    "module": "ESNext",
    "moduleResolution": "NodeNext",
    // 强制保留所有有值的导入，哪怕TS觉得它只是类型
    "preserveValueImports": true,
    // 如果开启了isolatedModules，也要确保它和preserveValueImports兼容
    "isolatedModules": true,
    // 其他原有配置...
  }
}

• preserveValueImports是核心：它会阻止TS移除那些看起来「没有被代码用到」的资源导入（因为TS默认会认为这种导入只是类型，没用就删掉）。
• module和moduleResolution设为ESNext/NodeNext，能确保导出的JS代码里保留标准的ES模块import语法，方便后续打包工具处理。

3. 确保gulp-typescript读取正确的配置 #

在你的gulp任务里，要让gulp-typescript完全使用tsconfig.json的配置，不要手动覆盖关键选项：

// gulpfile.js
const gulp = require('gulp');
const ts = require('gulp-typescript');

// 直接读取tsconfig.json创建项目，不要手动修改compilerOptions
const tsProject = ts.createProject('tsconfig.json');

gulp.task('build-ts', () => {
  return tsProject.src()
    .pipe(tsProject())
    .js.pipe(gulp.dest('dist'));
});

如果之前你在gulp里手动设置了module等选项，会覆盖tsconfig的配置，导致preserveValueImports不生效，这点要注意。

4. 验证导入语句的写法 #

确保你的TS代码里的导入是值导入，不是类型导入：

// 正确：值导入，TS会保留
import template from './my-template.html';

// 错误：类型导入，TS会直接移除
import type template from './my-template.html';

做完这些调整后，TypeScript编译后的JS文件里就会保留HTML的导入语句，Rollup或Webpack就能正常识别并处理这些资源了。

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