登录
当前位置： 首页 > 工具软件 > npm-es-modules > 使用案例 >

npm--package.json

宿建本
2023-12-01

原文网址：npm--package.json_IT利刃出鞘的博客-CSDN博客_npm package.json

简介

说明

本文介绍npm的package.json的用法。

官网

英文官网：package.json | npm 中文文档

翻译（不是很全）：npm的package.json中文文档 · Issue #6 · ericdum/mujiang.info · GitHub

文件 package.json 的说明文档

package.json简介

        package.json 位于模块的目录下，用于定义包的属性。例如：express 包的 package.json 文件，位于 node_modules/express/package.json。

        可以使用命令npm init来初始化一个package.json文件，运行这个命令后，它会询问一些关于包的基本信息，根据实际情况回答即可。如果不喜欢这种方式，可以使用npm init -y命令直接使用默认的配置来创建package.json文件，最后根据需要修改创建好的package.json文件即可。

        本文档有所有package.json中必要的配置。它必须是真正的json，而不是js对象。本文档中描述的很多行为都受npm-config(7)的影响。

简单示例

{
    "name": "my_package",
    "description": "",
    "version": "1.0.0",
    "description": "",
    "main": "index.js",
    "engines": {
        "node": ">= 0.10.0"
    },
    "scripts": {
        "dev": "node build/dev-server.js",
        "build": "node build/build.js",
        "docs": "node build/docs.js",
        "build-docs": "npm run docs & git checkout gh-pages & xcopy /sy dist\\* . & git add . & git commit -m 'auto-pages' & git push & git checkout master",
        "build-publish": "rmdir /S /Q lib & npm run build &git add . & git commit -m auto-build & npm version patch & npm publish & git push",
        "lint": "eslint --ext .js,.vue src"
    }

    "repository": {
        "type": "git",
        "url": "https://github.com/ashleygwilliams/my_package.git"
    },
    "keywords": [],
    "author": "",
    "license": "ISC",
    "bugs": {
        "url": "https://github.com/ashleygwilliams/my_package/issues"
    },
    "homepage": "https://github.com/ashleygwilliams/my_package"
}

默认值

npm会根据包内容设置一些默认值。

  • "scripts": {"start": "node server.js"}
    如果包的根目录有server.js文件，npm会默认将start命令设置为node server.js。
  • "scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}
    如果包的根目录有wscript文件，npm会默认将preinstall命令用node-waf进行编译。
  • "scripts":{"preinstall": "node-gyp rebuild"}
    如果包的根目录有binding.gyp文件，npm会默认将preinstall命令用node-gyp进行编译。
  • "contributors": [...]
    如果包的根目录有AUTHORS文件，npm会默认逐行按Name <email> (url)格式处理，邮箱和url是可选的。#号和空格开头的行会被忽略。

重要字段

        在package.json中_最_重要的就是name和version字段。他们都是必须的，如果没有就无法install。name和version一起组成的标识在假设中是唯一的。改变包应该同时改变version。

name

name是这个东西的名字。注意：

  • 不要把node或者js放在名字中。因为你写了package.json它就被假定成为了js，不过你可以用"engine"字段指定一个引擎（见后文）。
  • 这个名字会作为在URL的一部分、命令行的参数或者文件夹的名字。任何non-url-safe的字符都是不能用的。
  • 这个名字可能会作为参数被传入require()，所以它应该比较短，但也要意义清晰。
  • 要去npm registry查看一下这个名字是否已经被使用了。http://registry.npmjs.org/

规则

  • 必须小于或等于214个字符（包括@scope/for 范围包）。
  • 不能以点（.）或下划线（_）开头。
  • 名称中不得包含大写字母。
  • 必须仅使用URL安全字符。

version

        version必须能被node-semver解析，它被包在npm的依赖中。（要自己用可以执行npm install semver）

        可用的“数字”或者“范围”见semver(7).

任务

scripts

        “scripts”是一个由脚本命令组成的hash对象，他们在包不同的生命周期中被执行。key是生命周期事件，value是要运行的命令。

参见 npm-scripts(7)

config

"config" hash可以用来配置用于包脚本中的跨版本参数。在实例中，如果一个包有下面的配置：

{ "name" : "foo"
, "config" : { "port" : "8080" } }

        然后有一个“start”命令引用了npm_package_config_port环境变量，用户可以通过npm config set foo:port 8001来重写他。

参见 npm-config(7) 和 npm-scripts(7)。

依赖

简介

说明

        依赖是给一组包名指定版本范围的一个hash。这个版本范围是一个由一个或多个空格分隔的字符串。依赖还可以用tarball、git URL或者文件路径。

写法

写法

说明

version

完全和version一致

>version

大于version

>=version

大于等于version

<version 

小于version

<=version

小于等于version

~version  

允许最右侧版本(patch)升级，见semver(7).

更新包(npm update)的时候, 可以更新到最新的一个 patch版本。例：从 0.25.0 => 0.25.x,但不允许 0.26.x

^version

允许中间及右侧版本(minor)升级。例：允许从 16.0.0 => 16.x.x,但不允许 17.x.x

1.2.x

1.2.0, 1.2.1, 等，但不包括1.3.0

*

所有

""

空，同*

version1-version2 

同 >=version1 <=version2.

range1||range2 

二选一。

http://...

见下文'依赖URL'

git...

见下文'依赖Git URL'

user/repo

见下文'GitHub URLs'

如下面都是合法的：

{
    "dependencies": {
        "foo": "1.0.0 - 2.9999.9999",
        "bar": ">=1.0.2 <2.1.2",
        "baz": ">1.0.2 <=2.3.4",
        "boo": "2.0.1",
        "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
        "til": "~1.2",
        "elf": "^1.2.3",
        "two": "2.x",
        "thr": "3.3.x"
		"asd": "http://asdf.com/asdf.tar.gz",
		"pkg2": "file:./path/to/dir"
    }
}

可以依赖URL

依赖URL

可以指定一个tarball URL，这个tarball将在包被初始化的时候下载并初始化。

依赖Git URL

Git urls 可以是下面几种形式：

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish是可以被git checkout的任何tag、sha或者branch。默认为master。

GitHub URLs

1.1.65版后，你可以仅仅用“user/foo-project”引用GitHub urls，比如：

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express"
  }
}

各种dependencies

dependencies

将生产环境的依赖放到dependencies。

详见semver(7).

devDependencies

        将非生产环境的依赖（比如：测试、文档）放到devDependencies。

        如果有人要使用你的模块，他们可能不需要你开发使用的测试或者文档等依赖。在这种情况下，最好将这些附属的项目列在devDependencies中。这些东西会在执行npm link或者npm install的时候初始化，并可以像其他npm配置参数一样管理。详见npm-config(7)。

        对于非特定平台的构建步骤，比如需要编译CoffeeScript，可以用prepublish脚本去实现，并把它依赖的包放在devDependency中。（译者注：prepublish定义了在执行npm publish的时候先行执行的脚本）

比如：

{ "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepublish": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

        prepublish脚本会在publishing前运行，这样用户就不用自己去require来编译就能使用。并且在开发模式中（比如本地运行npm install）会运行这个脚本以便更好地测试。

peerDependencies

        在一些场景中，如在一个host中不必须进行require时候，你想表现你的package与一个host工具或者库的兼容关键。这一般用来引用插件，尤其是你的模块可能要暴露一个特定的接口，并由host文档来预期和指定。

比如：

{
  "name": "tea-latte",
  "version": "1.3.5"
  "peerDependencies": {
    "tea": "2.x"
  }
}

这能保证你的package可以只和tea的2.x版本一起初始化。npm install tea-latte可能会产生下面的依赖关系

├── tea-latte@1.3.5
└── tea@2.2.0

        试图初始化另一个有会冲突的依赖的插件将导致一个错误。因此，确保你的插件的需求约束越弱越好，而不要去把它锁定到一个特定的版本。

        假设这个host遵守semver规范，只改变这个package的主版本会打破你的插件。因此，如果你在package中用过每个1.x版本，就用"^1.0"或者"1.x"来表示。如果你依赖于功能介绍1.5.2，用">= 1.5.2 < 2"。

bundledDependencies

一组包名，他们会在发布的时候被打包进去。拼成"bundleDependencies"（缺d）也可以。

optionalDependencies

        如果一个依赖可用，但你希望在它安装错误的时候npm也能继续初始化，那么你可以把它放在optionalDependencies hash中。这是一个包名到版本或者url的map，就像dependencies hash一样。只是它运行错误。

        处理缺乏依赖也是你的程序的责任。比如像这样：

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

        optionalDependencies会覆盖dependencies中同名的项，所以通常比只放在一个地方好。

文件

files

        files指定包含在项目中的文件，以及项目的入口文件。项目包含的文件，可以是单独的文件、整个文件夹，或者通配符匹配到的文件。如果命名了一个文件夹，那也会包含文件夹中的文件。（除非被其他条件忽略了）你也可以提供一个.npmignore文件，让即使被包含在files字段中得文件被留下。其实就像.gitignore一样。

{
  "files": [
    "filename.js",
    "directory/",
    "glob/*.{js,json}"
  ]
}

main

        main字段配置一个文件名指向模块的入口程序。如果你包的名字叫foo，然后用户require("foo")，main配置的模块的exports对象会被返回。这应该是一个相对于根目录的文件路径。

{
  "main": "filename.js"
}

bin

        很多包都有一个或多个可执行的文件希望被放到PATH中。npm让妈妈再也不用担心了（实际上，就是这个功能让npm可执行的）。

        要用这个功能，给package.json中的bin字段一个命令名到文件位置的map。初始化的时候npm会将他链接到prefix/bin（全局初始化）或者./node_modules/.bin/（本地初始化）。

比如，npm有：

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

        所以，当你初始化npm，它会创建一个符号链接到cli.js脚本到/usr/local/bin/npm。

        如果你只有一个可执行文件，并且名字和包名一样。那么你可以只用一个字符串，比如：

{ "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

        指定一个单一的文件或者一个文件数组供man程序使用。

        如果只提供一个单一的文件，那么它初始化后就是man <pkgname>的结果，而不管实际的文件名是神马，比如：

{ "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文件了。

如果文件名不是以包名开头，那么它会被冠以前缀，下面的：

{ "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为后缀。The number dictates which man section the file is installed into.

{ "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 Packages规范说明了几种方式让你可以用directorieshash标示出包得结构。如果看一下npm's package.json，你会看到有directories标示出doc, lib, and man。

        在未来，这个信息可能会被用到。

directories.lib

        告诉屌丝们你的库文件夹在哪里。目前没有什么特别的东西需要用到lib文件夹，但确实是重要的元信息。

directories.bin

        如果你指定一个“bin”目录，然后在那个文件夹中得所有文件都会被当做"bin"字段使用。

        如果你已经指定了“bin”字段，那这个就无效。

directories.man

        一个放满man页面的文件夹。贴心地创建一个“man”字段。
        A folder that is full of man pages. Sugar to generate a "man" array by walking the folder.

directories.doc

        将markdown文件放在这里。最后，这些会被很好地展示出来，也许，某一天。
        Put markdown files in here. Eventually, these will be displayed nicely,maybe, someday.

directories.example

        将事例脚本放在这里。某一天，它可能会以聪明的方式展示出来。

types

        这是一个只在 TypeScript 中生效的字段，如果您的包有一个 main.js 文件，您还需要在 package.json 文件中指明主声明文件。 将 types 属性设置为指向 bundled 的声明文件。 例如：

{
  "types": "./lib/main.d.ts",
}

如果您的主声明文件名为 index.d.ts 并且位于包的根目录（index.js旁边），则不需要标记 types 属性，建议这样做。 

信息

description

放简介，字符串。方便屌丝们在npm search中搜索。

如果这个字段为空的话，默认会从当前目录的READMD.md或README文件读取第一行内容作为它的默认值。

keywords

关键字，数组、字符串。还是方便屌丝们在npm search中搜索。

license

        你应该要指定一个许可证，让人知道使用的权利和限制的。

        最简单的方法是，假如你用一个像BSD或者MIT这样通用的许可证，就只需要指定一个许可证的名字，像这样：

{ "license" : "BSD" }

更多示例

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}

         如果你有更复杂的许可条件，或者想要提供给更多地细节，可以这样:

"licenses": [{
		"type": "MyLicense",
		"url": "http://github.com/owner/project/path/to/license"
	}
]

license字段必须是以下之一:

  • 如果你使用标准的许可证，需要一个有效地 SPDX 许可证标识。
  • 如果你用多种标准许可证，需要有效的 SPDX 许可证表达式2.0语法表达式。
  • 如果你使用非标准的许可证，一个 SEE LICENSE IN <文件名> 字符串指向你的包里顶级目录的一个 <文件名>。
  • 如果你不想在任何条款下授权其他人使用你的私有或未公开的包，一个 UNLICENSED 字符串。

        鼓励使用开源 (OSI-approved) 许可证，除非你有特别的原因不用它。 如果你开发的包是你工作的一部分，最好和公司讨论后再做决定。

链接

homepage

项目官网的url。

注意：这和“url”_不_一样。如果你放一个“url”字段，registry会以为是一个跳转到你发布在其他地方的地址，然后喊你滚粗。

嗯，滚粗，没开玩笑。

repository

        指定你的代码存放的地方。这个对希望贡献的人有帮助。如果git仓库在github上，那么npm docs命令能找到你。

这样做：

"repository" :
  { "type" : "git"
  , "url" : "http://github.com/isaacs/npm.git"
  }

"repository" :
  { "type" : "svn"
  , "url" : "http://v8.googlecode.com/svn/trunk/"
  }

        URL应该是公开的（即便是只读的）能直接被未经过修改的版本控制程序处理的url。不应该是一个html的项目页面。因为它是给计算机看的。

bugs

        你项目的提交问题的url和（或）邮件地址。这对遇到问题的屌丝很有帮助。差不多长这样：

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

        你可以指定一个或者指定两个。如果你只想提供一个url，那就不用对象了，字符串就行。如果提供了url，它会被npm bugs命令使用。

项目维护

author

        author是一个人。有name字段，可选的有url、email字段的对象，像这样：

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

        或者可以把所有的东西都放到一个字符串里，npm会给你解析：

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

        email和url在两种形式中都是可选的。也可以在你的npm用户信息中设置一个顶级的maintainers字段。

contributors

贡献者信息，可能很多人。

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
}

或者 

{
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}

打包

module

pkg.module 将指向具有 ES2015 模块语法的模块，但仅指向目标环境支持的语法功能。 完整的描述在这里。

支持：rollup, webpack

browser

字段由模块作者提供，作为 JavaScript 包或组件工具的提示，用于打包模块以供客户端使用。 提案就在这里。

esnext

完整的提案在这里。 简短说明：

  • esnext：ES模块中使用阶段4功能（或更旧版本）的源代码，未编译。
  • main：指向一个CommonJS模块（或UMD模块），其 JavaScript 与 Node.js 当前可以处理的一样现代。
  • 大多数 module 用例应该可以通过 esnext 处理。
  • browser 可以通过 esnext 的扩展版本来处理
{
  "main": "main.js",
  "esnext": {
    "main": "main-esnext.js",
    "browser": "browser-specific-main-esnext.js"
  }
}

另请参阅：Delivering untranspiled source code via npm

发布

private

        如果你设置"private": true，npm就不会发布它。

        这是一个防止意外发布私有库的方式。如果你要确定给定的包是只发布在特定registry（如内部registry）的，用publishConfighash的描述来重写registry的publish-time配置参数。

publishConfig

        这是一个在publish-time使用的配置集合。当你想设置tag或者registry的时候它非常有用，所以你可以确定一个给定的包没有打上“lastest”的tag或者被默认发布到全局的公开registry。

        任何配置都可以被重写，但当然可能只有“tag”和“registry”与发布的意图有关。

系统

engines

你可以指定工作的node的版本：

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

        并且，像dependensies一样，如果你不指定版本或者指定“*”作为版本，那么所有版本的node都可以。

        如果指定一个“engines”字段，那么npm会需要node在里面，如果“engines”被省略，npm会假定它在node上工作。

        你也可以用“engines”字段来指定哪一个npm版本能更好地初始化你的程序，如：

{ "engines" : { "npm" : "~1.0.20" } }

        记住，除非用户设置engine-strict标记，这个字段只是建议值。

engineStrict

        如果你确定你的模块_一定不_会运行在你指定版本之外的node或者npm上，你可以在package.json文件中设置"engineStrict":true。它会重写用户的engine-strict设置。

        除非你非常非常确定，否则不要这样做。如果你的engines hash过度地限制，很可能轻易让自己陷入窘境。慎重地考虑这个选择。如果大家滥用它，它会再以后的npm版本中被删除。

os

你可以指定你的模块要运行在哪些操作系统中：

"os" : [ "darwin", "linux" ]

你也可以用黑名单代替白名单，在名字前面加上“!”就可以了：

"os" : [ "!win32" ]

操作系统用process.platform来探测。虽然没有很好地理由，但它是同时支持黑名单和白名单的。

cpu

如果你的代码只能运行在特定的cpu架构下，你可以指定一个：

"cpu" : [ "x64", "ia32" ]

就像os选项，你也可以黑一个架构：

"cpu" : [ "!arm", "!mips" ]

cpu架构用process.arch探测。

preferGlobal

        如果包主要是需要全局安装的命令行程序，就设置它为true来提供一个warning给只在局部安装的人。它不会真正的防止用户在局部安装，但如果它没有按预期工作它会帮助防止产生误会。

 类似资料：

相关阅读

npm install和npm run build有什么区别？无法安装npm软件包“ npm ERR！errno -4048”nodejs npm package.json中文文档用npm安装Expressnpm ERR！代码UNABLE_TO_GET_ISSUER_CERT_LOCALLY

相关文章

相关问答

无法运行npm命令“npm install-g tty.js”。“NPM安装”和“NPM CI”有什么区别？无法运行npm命令"npm安装-gtty.js"。错误： npm安装-g角-cli|npm ERR！Windows_NT10.0.10586如何设置npm根路径到.../Appdata/roaming/npm
快捷导航： 新手教程 算法原理 架构设计 Java进阶 数据库进阶 大厂专栏 面试经验 编程笔记 编程问答 所有专题 文档资料 工具软件 电子书籍 小牛导航
在线工具： 房贷计算器 个税计算器 Linux命令查询 Json格式化 正则表达式 颜色转换 AES加解密 SHA1加密 MD5加密 毒鸡汤 字数统计 随机密码生成 进制转换 Base64编解码 励志句子
Copyright © 2019-2024 小牛知识库@xnip.cn. All Rights Reserved.