ESM.sh 自托管服务对接 GitHub NPM 私有仓库的配置要点

在使用自托管 ESM.sh 服务对接 GitHub 的 NPM 私有仓库时，开发者可能会遇到 405 Method Not Allowed 错误。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象

当配置 ESM.sh 指向 GitHub 的 NPM 私有仓库时，尝试加载私有包会返回以下错误：

Error: [esm.sh] npm: could not get metadata of package '@my-org/my-package' (405 Method Not Allowed: )

尽管使用 curl 命令直接访问 GitHub 的 NPM 仓库可以正常工作，但在 ESM.sh 中却无法获取包元数据。

根本原因分析

经过排查发现，ESM.sh 的默认实现假设所有 NPM 仓库都遵循标准路径结构，即支持通过 /pkg/version 的 URL 格式获取包信息。然而，GitHub 的 NPM 仓库服务并未实现这一标准接口。

具体来说，ESM.sh 服务端代码中存在一个条件判断，会尝试使用非标准路径格式获取包信息。这一逻辑对于标准 NPM 仓库有效，但与 GitHub 的仓库实现不兼容。

解决方案

要解决这个问题，需要对 ESM.sh 的源代码进行修改，移除对非标准路径格式的尝试。具体修改如下：

1. 找到并注释掉服务端代码中尝试使用 /pkg/version 路径格式的逻辑
2. 确保只使用标准的包元数据获取方式

修改后，ESM.sh 将直接使用标准的 NPM 仓库 API 路径与 GitHub 仓库交互，从而避免 405 错误。

配置建议

除了代码修改外，正确的配置也很重要。以下是推荐的 ESM.sh 配置示例：

{
  "port": 8080,
  "workDir": "/path/to/workdir",
  "storage": "local:/path/to/storage",
  "npmRegistryScope": "@my-org",
  "npmRegistry": "https://npm.pkg.github.com",
  "npmToken": "your_github_token"
}

确保以下几点：

• 使用正确的 GitHub NPM 仓库地址
• 设置正确的组织范围（npmRegistryScope）
• 提供有效的 GitHub 访问令牌

验证方法

修改完成后，可以通过以下方式验证配置是否生效：

1. 重启 ESM.sh 服务
2. 尝试通过浏览器或 curl 访问私有包
3. 检查日志中是否还有 405 错误出现

总结

GitHub 的 NPM 仓库服务虽然功能完善，但在某些 API 实现上与标准 NPM 仓库存在差异。通过调整 ESM.sh 的请求逻辑，可以完美解决这一问题，实现自托管 ESM.sh 服务与 GitHub 私有 NPM 仓库的无缝集成。这一解决方案不仅适用于当前版本，也为未来可能的类似集成问题提供了参考思路。