Mcp-Swagger-Server

# npm 发布后 tslib 依赖缺失问题解决方案 ## 🐛 问题描述 当将 `mcp-swagger-server` 发布到 npm 仓库后，使用 `npx mcp-swagger-server` 运行时会出现以下错误： ``` Cannot find module 'tslib' ``` ## 🔍 问题根因分析 ### 1. TypeScript 编译配置 在 `tsconfig.json` 中设置了 `"importHelpers": true`： ```json { "compilerOptions": { "importHelpers": true, // ... 其他配置 } } ``` ### 2. 编译结果分析 当 `importHelpers: true` 时，TypeScript 编译器会： - 将常用的辅助函数（如 `__importDefault`, `__importStar`, `__exportStar`）外部化 - 在编译后的 JavaScript 代码中生成 `require('tslib')` 调用 - 这样可以减少代码重复，优化包大小 ### 3. 编译后的代码示例 ```javascript "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); const tslib_1 = require("tslib"); // ← 这里需要 tslib const axios_1 = tslib_1.__importDefault(require("axios")); const fs = tslib_1.__importStar(require("fs")); // ... ``` ### 4. 依赖缺失 原始的 `package.json` 中没有将 `tslib` 列为生产依赖，导致： - 本地开发时工作正常（因为 devDependencies 中可能有 tslib） - npm 发布后缺少运行时依赖，导致 `require('tslib')` 失败 ## ✅ 解决方案 ### 1. 添加 tslib 到生产依赖 在 `package.json` 中添加 `tslib` 到 `dependencies`： ```json { "dependencies": { // ... 其他依赖 "tslib": "^2.8.1" } } ``` ### 2. 版本号更新 将版本号从 `1.0.5` 更新到 `1.0.6` 以反映这个修复。 ### 3. 重新构建和测试 ```bash npm install npm run build node dist/cli.js --help # 验证本地构建 ``` ## 🎯 为什么选择这个解决方案 ### 方案对比 | 方案 | 优点 | 缺点 | 推荐度 | |------|------|------|--------| | 添加 tslib 依赖 | 简单直接，保持优化 | 增加一个依赖 | ⭐⭐⭐⭐⭐ | | 关闭 importHelpers | 无需额外依赖 | 增加包大小，代码重复 | ⭐⭐⭐ | | 使用 noEmitHelpers | 内联所有辅助函数 | 显著增加包大小 | ⭐⭐ | ### 选择 tslib 的原因 1. **官方推荐**：这是 TypeScript 官方推荐的最佳实践 2. **包大小优化**：避免在每个文件中重复辅助函数代码 3. **成熟稳定**：tslib 是 TypeScript 生态系统的标准组件 4. **影响最小**：只需添加一个小型、稳定的依赖 ## 🔧 预防措施 ### 1. 发布前检查清单 - [ ] 检查编译后的代码是否有 `require('tslib')` 调用 - [ ] 确认所有运行时依赖都在 `dependencies` 中 - [ ] 在干净的环境中测试 `npx` 命令 ### 2. 自动化检测脚本 可以创建测试脚本来验证依赖： ```javascript // test-dependencies.js const fs = require('fs'); const path = require('path'); // 检查编译后的代码中的依赖 function checkCompiledDependencies() { const distDir = './dist'; const packageJson = require('./package.json'); // 遍历编译后的文件 function scanDirectory(dir) { // ... 扫描 require() 调用 } // 验证依赖是否在 package.json 中 // ... } ``` ### 3. CI/CD 集成 在 GitHub Actions 或其他 CI 中添加发布前验证： ```yaml - name: Test global install run: | npm pack npm install -g ./package-name-*.tgz package-name --help ``` ## 📊 影响分析 ### 包大小变化 - `tslib`: ~10KB（压缩后 ~3KB） - 对比：不使用 tslib 可能增加 20-50KB（取决于项目大小） ### 性能影响 - 运行时性能：无显著影响 - 加载时间：略有改善（代码更少） - 内存使用：略有减少（共享辅助函数） ## 🎉 修复验证 ### 本地验证 ```bash ✅ npm run build # 构建成功 ✅ node dist/cli.js --help # 本地运行成功 ✅ node test-tslib.js # 依赖检测通过 ``` ### 发布后验证（待完成） ```bash npm publish # 发布新版本 npx mcp-swagger-server@1.0.6 --help # 全局安装测试 ``` ## 📚 相关文档 - [TypeScript Handbook - importHelpers](https://www.typescriptlang.org/tsconfig#importHelpers) - [tslib GitHub Repository](https://github.com/Microsoft/tslib) - [npm 包发布最佳实践](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) --- **总结**：这是一个典型的 TypeScript 项目发布时的依赖配置问题。通过添加 `tslib` 到生产依赖，问题得到了彻底解决。这个修复同时保持了代码优化的优势，是最佳的解决方案。