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"，以实现可预测、可审计的包发布行为。
