TypeScript+esbuild打包Ghost存储适配器时如何正确引入外部模块？

我正在使用@aws-sdk/client-s3为Ghost编写存储适配器，希望通过esbuild将其打包为单个独立文件。编写该适配器需继承Ghost提供的BaseStorageAdapter类，因此不想将ghost-storage-base模块打包。但使用不同导入语法引入该模块时，esbuild生成的输出文件各不相同，无法达到预期效果。

使用的打包命令：

npx esbuild src/index.ts --external:ghost-storage-base --bundle --platform=node

不同导入方式的输出情况：

• 移除导入语句：生成1.2MB文件，除未引入外部模块外，其余内容打包正常；
• 使用import StorageBase from "ghost-storage-base"：生成1.2KB文件，仅含模板代码与语句var import_ghost_storage_base = __toESM(require("ghost-storage-base"))；
• 使用var StorageBase = require("ghost-storage-base")：仅输出语句var StorageBase = require("ghost-storage-base")，无其他内容。

我的tsconfig.json配置极为基础：

{
    "include": [
        "src/**/*"
    ],
}

请问是esbuild命令调用错误？还是缺少TypeScript配置项？或是其他问题导致的？

问题原因与解决方案 #

核心原因 #

esbuild的Tree Shaking（摇树优化）会移除未被实际使用的代码。如果你的代码仅导入了ghost-storage-base，但没有通过继承、调用等方式触发依赖，或者TypeScript配置不规范导致代码依赖未被正确识别，esbuild就会把所有无关代码全部剔除，导致输出异常精简。

具体修复步骤 #

1. 完善TypeScript配置
   基础的tsconfig.json无法支撑模块兼容和类继承的正确编译，补充必要选项：

   {
       "include": ["src/**/*"],
       "compilerOptions": {
           "target": "ES2020",
           "module": "CommonJS",
           "moduleResolution": "Node",
           "esModuleInterop": true,
           "skipLibCheck": true,
           "strict": false,
           "outDir": "./dist"
       }
   }
   

   • esModuleInterop：确保CommonJS规范的ghost-storage-base能被ES模块语法正确导入；
   • module: CommonJS：匹配Node.js环境的模块规范，避免esbuild转换时出现兼容问题。

2. 确保代码实际使用StorageBase
   检查适配器类是否正确继承并实现Ghost要求的核心方法，且完成导出：

   import StorageBase from "ghost-storage-base";
   
   class S3StorageAdapter extends StorageBase {
       // 必须实现Ghost强制要求的核心方法
       async save(file) {
           // 你的S3上传逻辑代码
       }
   
       async exists(filename) {
           // 你的文件存在性检查逻辑代码
       }
   }
   
   // 必须导出适配器类，否则esbuild会判定代码无实际用途
   module.exports = S3StorageAdapter;
   

   注：如果仅继承但无方法实现或导出，esbuild依然会判定代码无用并移除。

3. 调整esbuild命令（可选）
   若Tree Shaking依然过度，可临时关闭优化排查问题，但建议优先确保代码被正确使用：

   npx esbuild src/index.ts --external:ghost-storage-base --bundle --platform=node --tree-shaking=false
   

验证标准 #

重新打包后，若输出文件大小回到1.2MB左右，包含@aws-sdk/client-s3的代码，同时保留require("ghost-storage-base")语句，说明问题解决。

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