esBuild watch模式下重构建不生成.d.ts类型文件如何解决

问题原因 #

当前配置中，.d.ts文件生成逻辑仅在esbuild首次构建完成后通过npm脚本执行一次。watch模式下esbuild触发增量重构建时，仅会运行onRebuild回调内的逻辑，现有回调仅打印构建结果日志，未触发类型声明生成命令，因此重构建后不会更新.d.ts文件。
另外原配置中entryPoints填写的/index.ts为系统根目录路径，属于路径写法错误，需修正为项目相对路径./index.ts。

解决方案 #

将类型声明生成逻辑整合到esbuild构建流程中，在首次构建成功、每次增量重构建成功后都自动执行tsc声明生成命令。

• 修改esbuild.js配置，引入node原生子进程模块执行tsc命令，完整配置如下：

const { build } = require('esbuild');
const { execSync } = require('child_process');

// 抽离类型声明生成逻辑
const genDeclaration = () => {
  try {
    execSync('tsc --emitDeclarationOnly --outDir dist', { stdio: 'inherit' });
    console.log('✅ 类型声明文件生成完成');
  } catch (err) {
    console.error('❌ 类型声明文件生成失败');
  }
}

build({
  entryPoints: ['./index.ts'], // 修正原路径错误
  outdir: 'dist',
  format: 'cjs',
  watch: {
    onRebuild(err) {
      if (err) {
        console.error('❌ 代码重构建失败', err);
        return;
      }
      console.log('🔄 代码重构建完成，开始更新类型声明');
      genDeclaration();
    }
  }
})
.then(() => {
  console.log('🚀 初始构建完成，开始生成类型声明');
  genDeclaration();
  console.log('👀 watch模式已启动，文件变更将自动同步构建代码与类型声明');
})
.catch(() => process.exit(1));

• 简化package.json中的脚本配置，移除原有冗余的ts-types触发逻辑：

"scripts": {
    "ts-types": "tsc --emitDeclarationOnly --outDir dist",
    "build": "node ./esbuild.js",
    "build:prod": "node ./esbuild.prod.js && npm run ts-types"
}

如果需要生产环境构建（不启动watch），可以单独写一份无watch配置的esbuild配置文件，走build:prod命令即可。

可选性能优化（适合中大型项目） #

如果项目文件较多，每次重构建触发全量tsc生成声明速度较慢，可以拆分监听进程，让esbuild和tsc各自运行watch模式，并行处理代码构建和类型生成，无需互相等待：

"scripts": {
  "watch": "concurrently \"node ./esbuild.js\" \"tsc -w --emitDeclarationOnly --outDir dist\""
}

上述写法使用concurrently实现跨平台并行执行命令，避免windows系统下不支持&并行符的问题，使用前需执行npm i concurrently -D安装依赖。

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