nodebestpractices 安全实践：如何避免在 npm 发布时意外泄露机密（.npmignore / files 白名单 / --dry-run 全解析）

• 文档
• 教程
• 后端

导读

本篇文章来自 nodebestpractices 仓库中安全实践清单第 6.25 条「Избегайте публикации секретов в реестре npm」（避免在 npm 注册表中发布机密），完整对应英文原文 avoid_publishing_secrets.md 及其俄语版本 avoid_publishing_secrets.russian.md。本文将从「为什么机密会搭上 npm 包一起外泄」这一现实风险出发，系统讲解.npmignore黑名单机制、package.json中files数组白名单机制、npm publish --dry-run预检手段，以及最容易被忽视的.npmignore覆盖.gitignore的优先级陷阱。读完本文，你将掌握一套可落地的「发布前自检 + 双清单防护」方案，确保 API 密钥、密码、.env等敏感文件不会随你的 Node.js 包进入公开 npm 注册表。

一、问题背景：机密为什么会出现在 npm 包里

在 README.russian.md 中，这条实践被归类为 OWASP A6（安全错误配置）威胁类别，其风险描述非常直接：

Ключи API вашего проекта, пароли или другие секреты открыты для злоупотребления любым, кто сталкивается с ними, что может привести к финансовым потерям, подлогу и другим рискам.

也就是说：一旦 API 密钥、密码或其他机密随包发布到公开 npm 注册表，任何下载该包的人都能拿到并滥用它们，可能导致经济损失、身份冒用等一系列后果。

泄露路径往往并非「故意发布机密」，而是发布动作本身过于宽松：npm publish默认会把当前目录下的几乎所有文件打成一个 tarball 包并上传，而开发者往往只关注了.gitignore（防止机密进入版本库），却忽略了 npm 打包的独立过滤规则，导致「Git 里没有的机密，npm 包里却有」。

二、第一道防线：.npmignore黑名单机制

原文档给出的第一类防护手段是使用.npmignore文件，将特定文件或目录显式列入黑名单，使其不进入发布包。原文档提供的完整示例文件如下：

# Tests test coverage # Build tools .travis.yml .jenkins.yml # Environment .env .config

这个示例清晰地展示了.npmignore的典型用法，按语义可分成三组：

需要特别强调的是.env这一行：许多项目把本地数据库口令、云厂商 API 密钥放在.env中，一旦随包发布，攻击者甚至无需破解仓库即可直接从 npm 下载 tarball 提取明文机密。

三、第二道防线：package.json的files白名单机制

与黑名单相对的，是利用package.json中的files数组建立白名单——只发布明确列出的文件。原文档给出的示例为：

{ "files" : [ "dist/moment.js", "dist/moment.min.js" ] }

白名单模式的思想是「默认全部排除，只放行需要的构建产物」。它与黑名单各有利弊：

• 黑名单（.npmignore）：维护成本低、不易误伤，但要求你清楚知道哪些文件是敏感的，漏掉一个就可能导致泄露；
• 白名单（files）：从源头杜绝「漏网之鱼」，但凡未列出的文件一律不进包，尤其适合「发布产物集中在dist/等目录」的构建型项目。

原文档还引用了 Snyk 博客（Liran Tal 与 Juan Picado 所著）的论述来佐证两者关系：

files属性在 package.json 中作为白名单，指定要被打包、创建和安装的文件的数组（而 ignore 文件充当黑名单）。files属性和 ignore 文件可以同时使用，以确定哪些文件应被显式包含、哪些应从包中排除。当两者同时使用时，package.json 中的files属性优先于 ignore 文件。

四、最危险的陷阱：.npmignore会覆盖.gitignore

这是原文档明确点名、也是实战中最常踩中的坑：

如果项目同时使用.npmignore和.gitignore，那么凡是.npmignore中没有列出的内容都会被发布到注册表——即.npmignore会覆盖（override）.gitignore。

理解这一点至关重要。很多开发者的习惯是：把敏感文件写进.gitignore，让机密不进版本库，然后想当然地认为 npm 也不会发布它。但 npm 打包时的判定规则与 Git 完全不同：

1. 若项目存在.npmignore，npm 只依据.npmignore的规则决定包含/排除，此时.gitignore完全不参与过滤；
2. 若项目不存在.npmignore，npm 才回退使用.gitignore作为参考。

由此产生一个典型事故链条：开发者更新了.gitignore（例如新增了某个含机密的文件），却忘记同步更新.npmignore，结果是——该文件虽然不会被推送到源码控制系统，却仍然会被打进 npm 包并公开发布。原文档对这一场景的表述为：「一个潜在敏感的文件没有被推送到版本控制系统，却仍然被包含在 npm 包中」。

规避策略：凡是同时在.gitignore和.npmignore中出现过的敏感条目（尤其.env、.config、密钥文件），必须保证两边清单长期同步；更稳妥的做法是直接采用上文的files白名单，让打包规则与 Git 规则彻底解耦。

五、发布前预检：npm publish --dry-run与npm pack

原文档给出的验证手段是--dry-run标志：

为了解npm publish实际将发布到注册表的内容，可以在npm publish命令上添加--dry-run标志，从而获得所创建 tarball 包的详细（verbose）视图。

具体用法为：

# 预览将要发布到注册表的包内容，不实际执行发布 npm publish --dry-run # 或在本地直接生成 tarball 并列出其中文件清单 npm pack

--dry-run会在终端输出即将被打包的完整文件树与元数据，是发布前检查机密是否残留的最直接手段。与之互补的是npm pack——它在本地生成.tgz归档，你可以随后执行tar -tzf <包名>.tgz逐项核对归档内文件，确认没有.env、密钥文件混入。

六、纵深防御：与仓库内其他机密管理实践的联动

在本仓库的安全实践体系中，本条「发布过滤」只是机密防护链条的一环，与其强相关的配套实践还包括：

• 源头治理——不把机密写进仓库：secretmanagement.russian.md 建议优先使用环境变量承载密钥（通过process.env读取），其「试金石」标准是：代码库能否在任意时刻开源而不会泄露任何凭据。若确需将机密纳入版本控制，则应使用加密存储而非明文。
• 构建期防护——Docker 镜像同理：docker/avoid-build-time-secrets.md 指出 Docker 18.09 引入的--secret构建标志可从文件安全传递机密，且不会残留在最终镜像、中间镜像或镜像提交历史中，这与 npm 发布包的「产物内不得残留机密」原则完全一致。
• 事后审计——提交钩子扫描：原文档在关联章节还提到借助 git 提交钩子工具对提交内容做机密审计，从开发流程入口提前拦截。

将「源头（环境变量/加密）→ 入口（提交钩子扫描）→ 产物（.npmignore/files+--dry-run预检）」三层组合起来，才能形成完整的机密防泄露闭环。

七、发布前检查清单（可复制到 CI）

综合原文档与仓库相关实践，建议在每次npm publish（尤其是发布到公开注册表）前执行以下清单：

1. 确认敏感条目已同步：.env、.config、私钥、证书、部署凭证等条目必须同时存在于.npmignore（或通过files白名单排除）；
2. 执行预检：运行npm publish --dry-run，核对输出文件树中无任何敏感文件；
3. 本地解包复核：运行npm pack后，用tar -tzf列出 tarball 内容逐一排查；
4. 考虑白名单兜底：对构建型项目优先使用files数组，从根本上杜绝「漏黑名单」；
5. 密钥轮换预案：一旦发现泄露，立即在云平台/服务商处轮换密钥，并撤销已发布版本；
6. 纳入 CI 流水线：将上述预检步骤固化为脚本或钩子，使发布动作无法绕过检查。

结语

在 nodebestpractices 的安全实践中，本条规则针对的是 npm 生态特有的「打包与版本控制规则不一致」盲区。核心要点可概括为一句话：Git 不追踪 ≠ npm 不发布。只要掌握.npmignore黑名单、files白名单、--dry-run预检三件套，并时刻警惕.npmignore覆盖.gitignore的优先级陷阱，就能有效杜绝机密随包外泄这一高频安全事故。

• 文档
• 教程
• 后端