我有一个简单的包裹。json文件,我想添加一个评论。有办法做到这一点吗,或者有什么hack可以做到这一点吗?
{
"name": "My Project",
"version": "0.0.1",
"private": true,
"dependencies": {
"express": "3.x",
"mongoose": "3.x"
},
"devDependencies" : {
"should": "*"
/* "mocha": "*" not needed as should be globally installed */
}
}
上面的示例注释在npm崩溃时不起作用。我还尝试了// style注释。
您总是可以滥用重复的键会被覆盖的事实。这就是我刚才写的:
"dependencies": {
"grunt": "...",
"grunt-cli": "...",
"api-easy": "# Here is the pull request: https://github.com/...",
"api-easy": "git://..."
"grunt-vows": "...",
"vows": "..."
}
然而,不清楚JSON是否允许复制键(参见
JSON语法是否允许在一个对象中重复键?它似乎与npm一起工作,所以我冒这个险。
推荐的破解方法是使用“//”键(来自nodejs邮件列表)。当我测试它时,它不能处理“依赖”部分。另外,文章中的例子使用了多个“//”键,这意味着npm不会拒绝具有重复键的JSON文件。换句话说,上面的hack应该总是好的。
更新:重复密钥的一个恼人的缺点是npm install——save无声地消除了所有重复密钥。不幸的是,它很容易被忽视,你善意的评论也消失了。
“//”攻击看起来仍然是最安全的。但是,多行注释也会被npm install -save删除。
总结一下这些答案:
添加一个名为//的顶级字段,其中包含一个注释字符串。这是可行的,但它很糟糕,因为你不能把评论放在他们正在评论的东西附近。
添加多个以//开头的顶级字段,例如包含注释字符串的//dependencies。这样更好,但仍然只允许您做顶级注释。不能注释单个依赖项。
在脚本中添加echo命令。这是可行的,但它很糟糕,因为您只能在脚本中使用它。
这些解决方案的可读性也都不是很好。它们增加了大量的视觉干扰,ide不会用语法将它们作为注释突出显示。
我认为唯一合理的解决方案是生成包。Json从另一个文件。最简单的方法是将JSON写成JavaScript,然后使用Node.js将其写入package.json。将该文件保存为package.json。chmod +x它,然后你可以运行它来生成你的package。json。
#!/usr/bin/env node
import { writeFileSync } from "fs";
const config = {
// TODO: Think of better name.
name: "foo",
dependencies: {
// Bar 2.0 does not work due to bug 12345.
bar: "^1.2.0",
},
// Look at these beautify comments. Perfectly syntax highlighted, you
// can put them anywhere and there no risk of some tool removing them.
};
writeFileSync("package.json", JSON.stringify({
"//": "This file is \x40generated from package.json.mjs; do not edit.",
...config
}, null, 2));
它使用//键来警告人们不要编辑它。\x40生成是故意的。它变成了@generated in package。Json,这意味着一些代码审查系统将在默认情况下崩溃该文件。
这是构建系统中的一个额外步骤,但它胜过这里的所有其他hack。
正如这个答案所解释的,//键是保留的,所以它可以常规地用于注释。//注释的问题是它不实用,因为它不能被多次使用。在包上删除重复的密钥。Json自动更新:
"//": "this comment about dependencies stays",
"dependencies": {}
"//": "this comment disappears",
"devDependencies": {}
另一个问题是// comment不能在依赖项和devDependencies中使用,因为它被视为常规依赖项:
"dependencies": {
"//": "comment"
}
npm犯错!代码EINVALIDPACKAGENAME
npm犯错!无效的包名“//”:名称只能包含url友好
字符
在NPM中工作的一个变通方法,而不是Yarn,是使用一个非字符串值:
"dependencies": {
"foo": ["unused package"],
}
一个在NPM和Yarn中工作的变通方法是添加一个注释作为语义版本控制的一部分:
"dependencies": {
"bar": "^2",
"foo": "^2 || should be removed in 1.x release"
}
注意,如果OR之前的第一部分不匹配,则可以解析来自注释的版本,例如1.x。
需要注释但没有安装的包应该移动到另一个键,例如dependencies //:
"dependencies //": {
"baz": "unused package",
}
到目前为止,这里的大多数“黑客”都建议滥用JSON。但是,为什么不滥用底层脚本语言呢?
最初的反应是把描述放在右边,使用# add comments here来包装它;然而,这在Windows上不起作用,因为标志(例如,npm run myframework -- --myframework-flags)将被忽略。我改变了我的响应,使其适用于所有平台,并增加了一些缩进的可读性。
{
"scripts": {
"help": " echo 'Display help information (this screen)'; npm run",
"myframework": "echo 'Run myframework binary'; myframework",
"develop": " echo 'Run in development mode (with terminal output)'; npm run myframework"
"start": " echo 'Start myFramework as a daemon'; myframework start",
"stop": " echo 'Stop the myFramework daemon'; myframework stop"
"test": "echo \"Error: no test specified\" && exit 1"
}
}
这将:
Not break JSON compliance (or at least it's not a hack, and your IDE will not give you warnings for doing strange, dangerous stuff)
Works cross platform (tested on macOS and Windows, assuming it would work just fine on Linux)
Does not get in the way of running npm run myframework -- --help
Will output meaningful info when running npm run (which is the actual command to run to get information about available scripts)
Presents a more explicit help command (in case some developers are not aware that npm run presents such output)
Will show both the commands and its description when running the command itself
Is somewhat readable when just opening package.json (using less or your favorite IDE)