npm package.json属性详解

简介: 笔记

概述

package.json必须是一个严格的json文件,而不仅仅是js里边的一个对象。其中很多属性可以通过npm-config来生成

name

package.json中最重要的属性是nameversion两个属性,这两个属性是必须要有的,否则模块就无法被安装,这两个属性一起形成了一个npm模块的唯一标识符。模块中内容变更的同时,模块版本也应该一起变化。name属性就是你的模块名称,下面是一些命名规则:

  • name必须小于等于214个字节,包括前缀名称在内(如 xxx/xxxmodule)。
  • name不能以"_"或"."开头
  • 不能含有大写字母
  • name会成为url的一部分,不能含有url非法字符
    下面是官网文档的一些建议:
  • 不要使用和node核心模块一样的名称
  • name中不要含有"js"和"node"。 It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)
  • name属性会成为模块url、命令行中的一个参数或者一个文件夹名称,任何非url安全的字符在name中都不能使用,也不能以"_"或"."开头
  • name属性也许会被写在require()的参数中,所以最好取个简短而语义化的值。
  • 创建一个模块前可以先到后边的网址查查name是否已经被占用. https://www.npmjs.com/
# 发布一个包的时候,需要检验某个包名是否存在
npm search <ModuleName>

name属性可以有一些前缀如 e.g. @myorg/mypackage.在npm-scope(7)的文档中可以看到详细说明

version

version必须可以被npm依赖的一个node-semver模块解析。具体规则见下面的dependencies模块

description

一个描述,方便别人了解你的模块作用,搜索的时候也有用。

keywords

一个字符串数组,方便别人搜索到本模块

homepage

项目主页url注意: 这个项目主页url和url属性不同,如果你填写了url属性,npm注册工具会认为你把项目发布到其他地方了,获取模块的时候不会从npm官方仓库获取,而是会重定向到url属性配置的地址。 (原文档中用了 spit(吐)这个单词,作者表示他不是在开玩笑:)

bugs

填写一个bug提交地址或者一个邮箱,被你的模块坑到的人可以通过这里吐槽,例如:

{
    "url" : "https://github.com/owner/project/issues",
    "email" : "project@hostname.com"
}

url和email可以任意填或不填,如果只填一个,可以直接写成一个字符串而不是对象。如果填写了url,npm bugs命令会使用这个url。

license

你应该为你的模块制定一个协议,让用户知道他们有何权限来使用你的模块,以及使用该模块有哪些限制。最简单的,例如你用BSD-3-Clause 或 MIT之类的协议,如下:

{ "license" : "MIT" }

你可以在https://spdx.org/licenses/ 这个地址查阅协议列表 。

和用户相关的属性: author, contributors

author是一个码农, contributors是一个码农数组。 person是一个有一些描述属性的对象,如下 like this:

{
    "name" : "Barney Rubble",
    "email" : "b@rubble.com",
    "url" : "http://barnyrubble.tumblr.com/"
}

也可以按如下格式缩写,npm会帮着转换:

"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)"

emailurl属性实际上都是可以省略的。描述用户信息的还有一个maintainers(维护者)属性。

files

files属性的值是一个数组,内容是模块下文件名或者文件夹名,如果是文件夹名,则文件夹下所有的文件也会被包含进来(除非文件被另一些配置排除了) 你也可以在模块根目录下创建一个.npmignore文件(windows下无法直接创建以"."开头的文件,使用linux命令行工具创建如git bash),写在这个文件里边的文件即便被写在files属性里边也会被排除在外,这个文件的写法".gitignore"类似。

main

main属性指定了程序的主入口文件。意思是,如果你的模块被命名为foo,用户安装了这个模块并通过require("foo")来使用这个模块,那么require返回的内容就是main属性指定的文件中 module.exports指向的对象。 它应该指向模块根目录下的一个文件。对大对数模块而言,这个属性更多的是让模块有一个主入口文件,然而很多模块并不写这个属性。

bin

很多模块有一个或多个需要配置到PATH路径下的可执行模块,npm让这个工作变得十分简单(实际上npm本身也是通过bin属性安装为一个可执行命令的) 如果要用npm的这个功能,在package.json里边配置一个bin属性。bin属性是一个已命令名称为key,本地文件名称为value的map如下:

{
    "bin" : { "myapp" : "./cli.js" }
}

模块安装的时候,若是全局安装,则npm会为bin中配置的文件在bin目录下创建一个软连接(对于windows系统,默认会在C:\Users\username\AppData\Roaming\npm目录下),若是局部安装,则会在项目内的./node_modules/.bin/目录下创建一个软链接。 因此,按上面的例子,当你安装myapp的时候,npm就会为cli.js在/usr/local/bin/myapp路径创建一个软链接。 如果你的模块只有一个可执行文件,并且它的命令名称和模块名称一样,你可以只写一个字符串来代替上面那种配置,例如:

{ 
    "name": "my-program",
    "version": "1.2.5", 
    "bin": "./path/to/program"
}

作用和如下写法相同:

{ 
    "name": "my-program", 
    "version": "1.2.5", 
    "bin" : { 
        "my-program" : "./path/to/program" 
    }
}

man

制定一个或通过数组制定一些文件来让linux下的man命令查找文档地址。 如果只有一个文件被指定的话,安装后直接使用man+模块名称,而不管man指定的文件的实际名称。例如:

{
    "name" : "foo",
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : "./man/doc.1"
}

通过man foo命令会得到 ./man/doc.1 文件的内容。 如果man文件名称不是以模块名称开头的,安装的时候会给加上模块名称前缀。因此,下面这段配置:

{ 
    "name" : "foo", 
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : [ "./man/foo.1", "./man/bar.1" ]
}

会创建一些文件来作为man foo和man foo-bar命令的结果。 man文件必须以数字结尾,或者如果被压缩了,以.gz结尾。数字表示文件将被安装到man的哪个部分。

{ 
    "name" : "foo", 
    "version" : "1.2.3",
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : [ "./man/foo.1", "./man/foo.2" ]
}

会创建 man foo 和 man 2 foo 两条命令。

directories

CommonJs通过directories来制定一些方法来描述模块的结构,看看npm的package.json文件https://registry.npmjs.org/npm/latest ,可以发现里边有这个字段的内容。目前这个配置没有任何作用,将来可能会整出一些花样来。

directories.lib

告诉用户模块中lib目录在哪,这个配置目前没有任何作用,但是对使用模块的人来说是一个很有用的信息。

directories.bin

如果你在这里指定了bin目录,这个配置下面的文件会被加入到bin路径下,如果你已经在package.json中配置了bin目录,那么这里的配置将不起任何作用。

directories.man

指定一个目录,目录里边都是man文件,这是一种配置man文件的语法糖。

directories.doc

在这个目录里边放一些markdown文件,可能最终有一天它们会被友好的展现出来(应该是在npm的网站上)

directories.example

放一些示例脚本,或许某一天会有用 - -!

相关文章
|
4月前
|
Web App开发 前端开发
Chrome 浏览器插件 V3 版本 Manifest.json 文件中 Action 的类型(Types)、方法(Methods)和事件(Events)的属性和参数解析
Chrome 浏览器插件 V3 版本 Manifest.json 文件中 Action 的类型(Types)、方法(Methods)和事件(Events)的属性和参数解析
212 0
|
4月前
|
JavaScript 前端开发 Shell
NPM 自定义 package.json 中 scripts 命令(& 与 && 的区别,cross-env 的使用)
NPM 自定义 package.json 中 scripts 命令(& 与 && 的区别,cross-env 的使用)
165 0
|
2月前
|
JavaScript 前端开发 CDN
前端 JS 经典:package.json 属性详解
前端 JS 经典:package.json 属性详解
29 1
|
3月前
|
JSON C++ 数据格式
【VsCode】通过tasks.json中的problemMatcher属性的fileLocation子属性设定问题的输出内容
【VsCode】通过tasks.json中的problemMatcher属性的fileLocation子属性设定问题的输出内容
38 3
|
2月前
|
JavaScript 开发工具 数据安全/隐私保护
npm包【详解】(内含npm包的开发、发布、安装、更新、搜索、卸载、查看、版本号更新规则、package.json详解等)
npm包【详解】(内含npm包的开发、发布、安装、更新、搜索、卸载、查看、版本号更新规则、package.json详解等)
65 0
|
3月前
|
JSON JavaScript 数据格式
1.js动态的往json数据添加新属性和值 2.JSON 和 JS 对象互转 3.对象转化为数组
1.js动态的往json数据添加新属性和值 2.JSON 和 JS 对象互转 3.对象转化为数组
43 0
|
10月前
|
JSON C++ 数据格式
【VsCode】通过tasks.json中的problemMatcher属性的fileLocation子属性设定问题的输出内容
vscode 对于 json 文件的解析方式的开源代码部分. 摘录 文件目录设定部分的说明:
172 0
|
4月前
|
JavaScript 开发者 资源调度
Spartacus 2211 开发版本采用 npm install 结合 package-lock.json 避免 build 出错
Spartacus 2211 开发版本采用 npm install 结合 package-lock.json 避免 build 出错
Spartacus 2211 开发版本采用 npm install 结合 package-lock.json 避免 build 出错
使用npm init需要注意的事情以及pageck.json文件介绍
使用npm init需要注意的事情以及pageck.json文件介绍
|
4月前
|
XML 存储 JSON
C# | 使用Json序列化对象时忽略只读的属性
将对象序列化成为Json字符串是一个使用频率非常高的功能。Json格式具有很高的可读性,同时相较于XML更节省空间。 在开发过程中经常会遇到需要保存配置的场景,比如将配置信息保存在配置类型的实例中,再将这个对象序列化成为Json字符串并保存。当需要加载配置时,则是读取Json格式的字符串再将其还原成配置对象。在序列化的过程中,默认会将所有公开的属性和字段都序列化进入Json字符串中,这其中也会包含只读的属性或字段,而只读的属性和字段在反序列化的过程中其实是无意义的,也就是说这一部分存储是多余的。 本文将讲解如何在执行Json序列化时,忽略掉那些只读的属性和字段。
145 0
C# | 使用Json序列化对象时忽略只读的属性

推荐镜像

更多