package.json 查漏补缺——配置详解

下面的内容基本都是从官方文档上整理过来的。介绍一些比较重要的字段,不太常见的就不写了。详细内容可以查看官方文档

name 包名

如果你需要发布包,nameversion 是必不可少的字段。如果不需要发布,那这两个是可选的。

name 的命名有一些规范:

  • 长度 <= 214个字符,包含 scoped package 的 scope
  • 如果是 scoped package, 名称可以以 . 和 _ 开头
  • 不能包含大写字母
  • 由于名称会作为 URL、命令行参数和文件夹名的一部分,所以不能包含不安全的 URL 字符

注意:

  • 不要使用和核心 node 模块相同的名称
  • 不要包含 "js" 或者 "node"
  • 名称尽量精简、易于理解
  • 命名前,检查一下 www.npmjs.com 是否有重复的 package

name 可以拥有前缀,e.g. @myorg/mypackage

version 版本号

需要符合 semver 的规范。e.g. 1.1.0 or 1.1.0-alpha.1

description 描述

package 的描述信息,是一个字符串。它可以被 npm search 查询到。 npm search sqlite

keywords 关键词

package 的关键词,是一个字符串数组。同样可以被 npm search 查询到。

homepage 首页

项目的首页

json 复制代码
{
    "homepage": "https://github.com/owner/project#readme"
}

bugs

issue tracker 的 url 或者 email 地址。可以直接提供一个对象或者 url 字符串

json 复制代码
{ 
    "bugs": {
        "url" : "https://github.com/owner/project/issues", 
        "email" : "project@hostname.com"
    }
}
json 复制代码
{ 
    "bugs": "https://github.com/owner/project/issues"
}

如果提供了 url,它可以被 npm bugs 命令使用,执行该命令会打开对应的网址。

license 许可证

参考 the full list of SPDX license IDs 选择合适的 identifier

json 复制代码
{ 
    "license": "BSD-3-Clause"
}

如果你不想授予其他人使用一个私有的或者未发布的 package,你可以这么写:

json 复制代码
{ 
    "license": "UNLICENSED"
}

并设置 "private": true 防止不小心发布 package。

author,contributors

author 包含 name 以及可选的 urlemail。 例如

json 复制代码
{ 
    "name": "Barney Rubble", 
    "email": "b@rubble.com",
    "url": "http://barnyrubble.tumblr.com/"
} 

也可以直接一个字符串

json 复制代码
{ "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)" }

email 和 url 都是可选的。

files 文件

该字段是可选的,用于指定包发布时需要包含的文件或目录的字段。它的语法类似 .gitignore,但是作用是相反的。

你也可以提供一个 .npmignore 文件,防止某些文件被上传。当 .gitignore 文件存在时,.npmignore 会被忽略。

某些文件总是会被上传,如:

  • package.json
  • README
  • LICENSE / LICENCE
  • main 字段中指定的文件

READMELICENSE 可以使用任何大小写形式和文件扩展名

相应的,一些文件也总是会被忽略,如:

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • .*.swp
  • .DS_Store
  • ._*
  • npm-debug.log
  • .npmrc
  • node_modules
  • config.gypi
  • *.orig
  • package-lock.json

main

main 字段用于指定一个模块 ID,表示包的主要入口点。当用户在程序中使用 require("your-package-name") 引入你的包时,main 字段所指定的模块将被返回。

通常情况下,main 字段的值是相对于包根目录的模块路径。例如,如果你的包名为 foo,并且你的主模块位于 lib/index.js,那么你可以在 package.json 文件中设置如下的 main 字段:

json 复制代码
{
  "name": "foo",
  "version": "1.0.0",
  "description": "My package",
  "main": "lib/index.js"
}

这样,当用户在程序中使用 require("foo") 引入你的包时,lib/index.js 模块将被返回。

如果你的包只有一个主要的模块,那么通常情况下只需要设置 main 字段就可以了。如果你的包有多个模块,那么可以考虑使用 exports 字段来指定每个模块的入口点。

值得注意的是,如果你没有设置 main 字段,npm 会默认使用包根目录下的 index.js 作为主模块。因此,如果你的包的主模块就是 index.js,那么可以省略 main 字段。

browser

如果你的模块是针对客户端浏览器使用的,那么应该使用 browser 字段来代替 main 字段。

使用 browser 字段的目的是为了解决在浏览器中使用 Node.js 模块的常见问题。在浏览器中,一些 Node.js 模块中常用的 API(例如 fschild_process 等)是不可用的,因此需要提供替代的实现或者使用其他的库来实现相同的功能。在这种情况下,使用 browser 字段可以指定一个浏览器端可用的模块路径或文件,这个路径或文件应该是相对于包根目录的。

例如,如果你的包有一个主模块 lib/main.js,但是它依赖了 Node.js 模块 fs,那么你可以在 package.json 文件中设置如下的 browser 字段:

json 复制代码
{
  "name": "my-package",
  "version": "1.0.0",
  "description": "My package",
  "main": "lib/main.js",
  "browser": "lib/main.browser.js"
}

在上面的示例中,我们指定了一个名为 lib/main.browser.js 的替代模块,用于在浏览器中使用。当用户在浏览器中使用你的包时,浏览器将加载 lib/main.browser.js 模块,而不是 lib/main.js 模块。

bin

bin 字段用于指定一个或多个可执行文件的名称和路径。当使用 npm install 命令安装该包时,这些可执行文件将会被安装到系统的 PATH 中,以便在命令行中直接运行。

具体来说,bin 字段是一个对象,其中的键表示可执行文件的名称,值表示可执行文件的路径。例如,假设你的包中有一个名为 my-script 的可执行文件,其路径为 ./bin/my-script.js,那么你可以在 package.json 文件中添加以下内容:

json 复制代码
{
  "name": "my-package",
  "version": "1.0.0",
  "bin": {
    "my-script": "./bin/my-script.js"
  }
}

这告诉 npm 在安装时将 my-script 可执行文件添加到 PATH 中。这样,其他人在安装了你的包后就可以在命令行中直接运行 my-script 命令了。

如果你的包有多个可执行文件,可以在 bin 字段中添加多个键值对,每个键值对对应一个可执行文件。例如:

json 复制代码
{
  "name": "my-package",
  "version": "1.0.0",
  "bin": {
    "my-script": "./bin/my-script.js",
    "my-other-script": "./bin/my-other-script.js"
  }
}

在这个例子中,my-package 包将会在安装时将两个可执行文件 my-scriptmy-other-script 添加到系统的 PATH 中。

另外,请确保你在 bin 中引用的文件,其内容是以 #!/usr/bin/env node 开头,不然无法执行。

repository

指定代码存放的位置。运行 npm docs 将打开对应的网址。

json 复制代码
{
    "repository": {
        "type": "git",
        "url": "https://github.com/npm/cli.git"
    }
}

如果你的 package 是一个 monorepo 项目的一部分,你可以像这样指定目录:

json 复制代码
{
    "repository": {
        "type": "git",
        "url": "https://github.com/facebook/react.git"
        "directory": "packages/react-dom"
    }
}

config

config 可以给 scripts 提供配置,像这样:

json 复制代码
{
  "name": "test-npm-config",
  "packageManager": "yarn@3.6.1",
  "scripts": {
    "start": "node index.js --port=$npm_package_config_port"
  },
  "config": {
    "port": "8080"
  }
}

只有通过 npm run start 才能访问到这个变量。如果要设置环境变量,更推荐使用 cross-env

scripts

scripts 属性支持一系列内置脚本和生命周期事件,以及自定义脚本。这些脚本可以通过运行 npm run-script <stage>npm run <stage>(简写)来执行。与之匹配的前置和后置命令也会被执行(例如 premyscriptmyscriptpostmyscript)。还可以通过 npm explore <pkg> -- npm run <stage> 来运行依赖包中的脚本。

Life Cycle Scripts

有一些特别的生命周期脚本只会在某些情况下发生。

  • prepare, prepublish, prepublishOnly, prepack, postpack, dependencies

prepare

这个适合执行编译构建之类的任务。

Environment

path

当执行 scripts 里的脚本时,./node_modules/.bin 等会被添加 PATH 中,所以你可以直接执行某些命令。

json 复制代码
{
    "scripts": {
        "dev": "vite dev"
    },
    "devDependencies": {
        "vite": "^4.4.7"
    }
}

package.json vars

参考上面讲的 config。 如果你的 package.json 文件中有 { "name": "foo", version: "1.2.5" }, 那么在 scripts 中你就可以访问到 npm_package_namenpm_package_version 这两个环境变量。

dependencies

这个定义的是生产依赖,以下都是正确的写法。

json 复制代码
{
    "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",
        "asd": "http://asdf.com/asdf.tar.gz",
        "til": "~1.2",
        "elf": "~1.2.3",
        "two": "2.x",
        "thr": "3.3.x",
        "lat": "latest",
        "dyl": "file:../dyl"
    }
}

Git URL

text 复制代码
git+ssh://git@github.com:npm/cli.git#v1.0.27 
git+ssh://git@github.com:npm/cli#semver:^5.0 
git+https://isaacs@github.com/npm/cli.git 
git://github.com/npm/cli.git#v1.0.27

Github URL

json 复制代码
{
    "name": "foo",
    "version": "0.0.0",
    "dependencies": {
        "express": "expressjs/express",
        "mocha": "mochajs/mocha#4727d357ea",
        "module": "user/repo#feature\/branch"
    }
}

Local Path

text 复制代码
../foo/bar
~/foo/bar
./foo/bar
/foo/bar
json 复制代码
{
    "name": "baz",
    "dependencies": {
        "bar": "file:../foo/bar"
    }
}

注意,当运行 npm install 时,通过本地路径链接的包将不会安装它们自己的依赖项。你必须在本地路径中运行 npm install

devDependenices

开发环境依赖。

overrides

overrides 用于覆盖 package.json 文件中的依赖项版本。

json 复制代码
{
  "name": "my-package",
  "version": "1.0.0",
  "dependencies": {
    "react": "^16.0.0"
  },
  "devDependencies": {
    "enzyme": "^3.0.0"
  },
  "overrides": {
    "react": "^15.0.0",
    "enzyme": "^2.0.0"
  }Ï
}

上面 react 的版本被指定为 ^15.0.0enzyme 的版本被指定为 ^2.0.0。这是比较常见的用法,还有其他的用法。比如依赖的子依赖版本也可以被修改。

json 复制代码
{
    "overrides": {
        "foo": {
            ".": "1.0.0",
            "bar": "1.0.0"
        }
    }
}

这里 foo 的版本指定为 1.0.0, 它的依赖项 bar 被指定为 1.0.0官方文档

workspaces

这是 monorepo 项目会用到的字段,常见的配置如下。

json 复制代码
{
    "name": "workspace-example",
    "workspaces": [
        "./packages/*",
        "./apps/*"
    ]
}

有关 workspaces 的详细内容,可以看官方文档

相关推荐
如若12312 分钟前
对文件内的文件名生成目录,方便查阅
java·前端·python
滚雪球~1 小时前
npm error code ETIMEDOUT
前端·npm·node.js
沙漏无语1 小时前
npm : 无法加载文件 D:\Nodejs\node_global\npm.ps1,因为在此系统上禁止运行脚本
前端·npm·node.js
supermapsupport1 小时前
iClient3D for Cesium在Vue中快速实现场景卷帘
前端·vue.js·3d·cesium·supermap
brrdg_sefg1 小时前
WEB 漏洞 - 文件包含漏洞深度解析
前端·网络·安全
胡西风_foxww1 小时前
【es6复习笔记】rest参数(7)
前端·笔记·es6·参数·rest
m0_748254881 小时前
vue+elementui实现下拉表格多选+搜索+分页+回显+全选2.0
前端·vue.js·elementui
星就前端叭2 小时前
【开源】一款基于Vue3 + WebRTC + Node + SRS + FFmpeg搭建的直播间项目
前端·后端·开源·webrtc
m0_748234522 小时前
前端Vue3字体优化三部曲(webFont、font-spider、spa-font-spider-webpack-plugin)
前端·webpack·node.js
Web阿成2 小时前
3.学习webpack配置 尝试打包ts文件
前端·学习·webpack·typescript