您如何使用 package.json 中的“文件”和“目录”属性？

Posted 2023-03-07

【中文标题】您如何使用 package.json 中的“文件”和“目录”属性？

【英文标题】：How do you use the 'files' and 'directories' properties in package.json?

【发布时间】：2017-04-09 07:32:51

【问题描述】：

如果package.json 具有files 属性和/或directories 属性：

  "files": [
    "./src/assets/fonts/"
  ],
  "directories": 
     "assets:": "./src/assets"
  

有哪些方法可以利用它们？文档没有提到一旦指定它们可以做什么。

例如，files docs 说：

“文件”字段是要包含在项目中的文件数组。如果您在数组中命名一个文件夹，那么它还将包含该文件夹内的文件。

“包含在您的项目中”是什么意思？包括在哪里？以前无法访问它们现在如何访问？

在directories section 中，文档说：

将来，这些信息可能会以其他创造性的方式使用。

目前有哪些创造性的使用方式？

【问题讨论】：

不幸的是，在 javascript 世界中，诸如“文件模式遵循与 .gitignore 类似的语法，但颠倒了”之类的内容就是您将获得的所有文档。我想知道有多相似？您通常希望找到一种语法，或者至少参考其他一些关于如何解释值的规范。

【参考方案1】：

“包含在您的项目中”意味着文件将在您运行npm publish 时创建的打包tarball 中。您还可以运行 npm pack 来生成 tarball 以供检查，而无需实际触发发布。通过这种方式，您实际上可以打开生成的 tarball 并检查哪些文件已包含/未包含。

虽然.npmignore（或.gitignore 作为代理，如果没有.npmignore）作为要忽略的文件的黑名单（因此默认情况下包括其他所有文件），files 数组是白名单。也就是说，如果指定了 files 数组，则默认情况下不会包含所有内容，而是默认排除所有内容，并且只有明确列出的那些文件才会包含在打包的 tarball 中。

例如，假设您的包是一个用于在浏览器中使用的库。你的代码在lib/ 中，你运行browserify 编译成dist/index.js 的浏览器兼容库。您从.gitignore 中列出的一堆文件开始，这些文件用作不存在的事实上的.npmignore。但是现在dist/ 充满了生成的文件，您希望它们从 git 存储库中被忽略。如果将它们添加到 .gitignore，它们将从 git 存储库中排除，但它们也会从包 tarball 中被忽略。所以你有两个选择：将你的.gitignore 复制为.npmignore，但只在.gitignore 中列出dist/。如果你这样做，你将不得不保持两个文件几乎但不完全同步。这种方式乏味且容易出错。

另一种选择是没有.npmignore，而只是在files 数组中列出您在包中实际需要的文件。 README.*、package.json、CHANGELOG.*（可能还有其他几个）无论如何都会自动包含在 tarball 中。因此，您只需添加 "files": [ "dist" ] 即可。现在您的包 tarball 将不包含来自 lib 的原始源 JS，也不包含 tests/ 等，而是仅包含 dist/ 中的实际编译库。

至于directories，我通常列出lib（用于es5）、src（用于es6、coffeescript、typescript等源）、dist（用于浏览器或特定于vm的构建）、@987654351 @、output（用于临时生成的文件，如覆盖率报告等）、doc 等。虽然 npm 或其他工具不直接使用此属性，但它使目录结构明确。此外，它使目录在 npm 脚本中可引用，如下所示：

"scripts": 
  "clean": "rm -rf $npm_package_directories_dist $npm_package_directories_output",
  "lint": "eslint $npm_package_directories_src",
  "test": "teenytest $npm_package_directories_test",

这样，目录只被指定一次，如果它们改变了，它们只需要在一个位置（而不是整个package.json中的很多）改变。

【讨论】：

对于我来说，文件显示在 tarball 内容中，但在 node-mosules 文件夹中不可用。你知道可能是什么问题吗？

您现在也可以使用npm publish --dry-run 来准确找出包含哪些文件，而无需执行实际的发布步骤