npm publish 默认忽略的文件模式清单（含规避方法与最佳实践）

npm publish 命令内置一组硬编码的忽略规则，会无条件排除特定名称的文件和目录（如 .git、.DS_Store、npm-debug.log 等），即使未在 .npmignore 或 package.json#files 中声明；本文完整列出这些模式，并说明如何安全覆盖及验证。

npm publish 命令内置一组硬编码的忽略规则，会无条件排除特定名称的文件和目录（如 `.git`、`.ds_store`、`npm-debug.log` 等），即使未在 `.npmignore` 或 `package.json#files` 中声明；本文完整列出这些模式，并说明如何安全覆盖及验证。

在使用 npm publish 发布包时，开发者常遇到“文件莫名消失”的问题——例如名为 src 的子目录未出现在最终发布的 tarball 中，但既未被 .npmignore 显式排除，也未在 package.json 的 "files" 字段中遗漏。这种现象往往源于 npm 内置的强制忽略规则（hardcoded ignore patterns）：它们独立于用户配置，在打包前由 npm CLI 直接过滤，优先级高于 .gitignore 和 .npmignore。

✅ npm publish 永远忽略的文件/目录模式（截至 npm v9）

以下模式匹配的文件或目录始终被排除，无论其路径深浅（如 ./src/、./packages/core/src/ 均适用）：

.*.swp
._*
.DS_Store
.git
.gitignore
.hg
.npmignore
.npmrc
.lock-wscript
.svn
.wafpickle-*
config.gypi
CVS
npm-debug.log

? 注意：src 本身不在该列表中。你遇到的 src 被忽略，极可能源于其他原因（如 package.json 中 "files" 字段未包含 "src"，或存在隐式 .npmignore 规则）。npm 官方明确说明：src/ 是完全合法且默认可发布的目录名——它不匹配任何硬编码模式。

? 如何验证与调试实际发布内容？

在执行 npm publish 前，务必用 npm pack 预览生成的 tarball 内容：

Pix2Pix

使用Prompt编辑视频

下载

# 生成并查看压缩包结构（不上传）
npm pack --dry-run

# 或解压后检查
npm pack && tar -tzf package-name-1.0.0.tgz

若发现关键文件缺失，按以下顺序排查：

1. 检查 package.json 是否定义了 "files" 字段 —— 一旦声明，仅该字段指定的路径会被包含（白名单模式）；
2. 检查项目根目录是否存在 .npmignore；若无，则回退至 .gitignore（但硬编码规则仍优先生效）；
3. 运行 npm ls --depth=0 确认当前工作区无意外的 publishConfig 覆盖；
4. 使用 npm config list 确认无全局 .npmrc 干预。

⚠️ 覆盖硬编码规则？不推荐，但有例外方式

npm 不提供禁用硬编码忽略的开关。唯一合法绕过方式是：在 .npmignore（或 .gitignore）中使用 ! 取反规则显式“恢复”——但仅对部分模式有效（如 !.DS_Store 在某些 npm 版本中生效，而 !.git 则永远失败，因 .git 是核心元数据，禁止发布属安全强制策略）。

✅ 推荐做法：

• 始终显式声明 "files" 字段，精确控制发布内容（例："files": ["dist", "lib", "index.js", "README.md"]）；
• 避免依赖隐式包含逻辑；
• 将构建产物（如 dist/）与源码（如 src/）分离，并确保 "files" 包含目标目录。

✅ 总结

遵循“显式优于隐式”原则，主动管理 package.json#files，即可彻底规避此类陷阱，保障发布结果可预测、可复现。