npx esbuild 因类型声明文件导出不匹配报错，如何屏蔽错误？

问题背景 #

在index.tsx中导入了仅用于类型校验的permissions：

import { permissions } from './permissions';

permissions.ts仅做类型声明：

export declare var permissions : {
/* 内容已省略 */
}

TypeScript编译后，index.js保留导入语句，但permissions.js仅输出export {};，导致esbuild抛出错误：

No matching export in "out2/permissions.js" for import "permissions"

实际permissions是页面全局变量，代码运行逻辑正常，仅构建环节报错。

解决方案 #

方案1：改用环境声明文件（推荐） #

将permissions.ts重命名为permissions.d.ts，修改内容为全局类型声明：

declare global {
  var permissions: {
    /* 你的类型定义 */
  };
}

export {};

之后index.tsx中无需再导入permissions，直接使用即可，TypeScript会自动识别全局变量的类型，同时esbuild不会处理.d.ts文件，彻底避免编译冲突。

方案2：标记为外部依赖 #

通过esbuild配置将./permissions标记为外部依赖，让esbuild跳过对其导出的检查：

• 命令行方式：

  npx esbuild index.tsx --bundle --outfile=out2/index.js --external:./permissions
  

• 配置文件方式（如esbuild.config.js）：

  require('esbuild').build({
    entryPoints: ['index.tsx'],
    bundle: true,
    outfile: 'out2/index.js',
    external: ['./permissions'],
  }).catch(() => process.exit(1));
  

这样esbuild会保留导入语句，但不会去验证permissions.js的导出内容，运行时直接使用全局变量。

方案3：添加占位符导出 #

修改permissions.ts，添加一个指向全局变量的占位符导出，同时保证类型声明有效：

export declare var permissions: {
  /* 你的类型定义 */
};

// 运行时取全局变量，esbuild会识别此导出
export const permissions = globalThis.permissions;

编译后permissions.js会包含有效的导出，esbuild不再报错，TypeScript也能正常校验类型。

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