npm publish 默认忽略的文件名模式详解

npm publish 命令在打包发布时，会无条件忽略一组硬编码的文件与目录（如 .git、.DS_Store、npm-debug.log 等），无论 package.json 的 “files” 字段或 .npmignore/.gitignore 中是否显式声明，这些模式均优先生效。

npm publish 命令在打包发布时，会无条件忽略一组硬编码的文件与目录（如 `.git`、`.ds_store`、`npm-debug.log` 等），无论 `package.json` 的 `”files”` 字段或 `.npmignore`/`.gitignore` 中是否显式声明，这些模式均优先生效。

在使用 npm publish 发布 Node.js 包时，开发者常遇到“明明没写 .npmignore，也没在 package.json#files 中排除，但某些文件却莫名消失”的问题——例如嵌套层级中的 src/ 目录未被包含。这并非配置疏漏，而是 npm 内置了一组强制忽略规则（hardcoded ignore patterns），它们在任何用户配置之前即生效，且无法通过常规方式覆盖（除非显式列入 “files” 白名单）。

✅ npm publish 永久忽略的文件/目录列表

根据 npm 官方开发者文档，以下路径始终被排除，无需 .npmignore 或 .gitignore 参与：

.*.swp        # Vim 交换文件 ._*           # macOS 元数据文件（如 ._package.json） .DS_Store     # macOS 目录元数据 .git          # Git 版本库目录 .gitignore    # Git 忽略配置文件 .hg           # Mercurial 版本库目录 .npmignore    # npm 忽略配置文件（自身不参与打包） .npmrc        # npm 配置文件 .lock-wscript # Waf 构建系统锁文件 .svn          # Subversion 版本库目录 .wafpickle-*  # Waf 构建缓存文件 config.gypi   # Node.js GYP 配置文件 CVS           # CVS 版本库目录 npm-debug.log # npm 调试日志

⚠️ 注意：src/ 不在该默认忽略列表中。你遇到的 src 目录缺失，极可能源于其他原因——例如：

• package.json 中 “files” 字段未显式包含 “src”（npm 默认仅包含 package.json、README、LICENSE、CHANGELOG 等少数文件，不递归包含 src/）；
• 存在隐式 .npmignore（即使为空，也会禁用 .gitignore 回退逻辑）；
• src/ 被父级 .gitignore 或项目根 .npmignore 规则匹配（如 node_modules/ 同级的 * 或 **/*）。

? 如何验证实际发布的文件？

使用 npm pack –dry-run 可预览将被打包的文件列表（不真正发布）：

$ npm pack --dry-run npm notice  npm notice ?  my-package@1.0.0 npm notice === Tarball Contents === npm notice 1.2kB package.json npm notice 567B  README.md npm notice 2.1kB lib/index.js npm notice === Tarball Details === npm notice name:          my-package npm notice version:       1.0.0 npm notice filename:      my-package-1.0.0.tgz npm notice package size:  1.8 kB npm notice unpacked size: 3.9 kB npm notice shasum:        1a2b3c4d5e6f... npm notice integrity:     sha512-... npm notice total files:   3

若 src/ 未出现在输出中，说明它被 files 白名单遗漏或被某条 ignore 规则捕获。

✅ 推荐实践：明确控制发布内容

为避免意外遗漏，强烈建议显式声明 “files” 字段：

{   "name": "my-package",   "version": "1.0.0",   "files": [     "lib",     "index.js",     "README.md",     "LICENSE"   ] }

✅ 此方式安全、可读、可维护；
❌ 避免依赖默认行为（npm 默认仅包含极少数文件，不会自动包含 src/、test/、examples/ 等常见目录）。

? 总结

• npm publish 的“某些模式”是硬编码的 13 类路径，涵盖版本控制元数据、编辑器临时文件、构建产物及 npm 自身配置文件；
• src/ 不在此列，其缺失通常源于 files 未声明或 ignore 规则误匹配；
• 使用 npm pack –dry-run 是诊断发布内容最直接的方法；
• 最佳实践：始终在 package.json 中明确定义 “files”，以实现可预测、可审计的包发布行为。