教程文档【免费下载链接】jstutorialJavascript tutorial book项目地址https://gitcode.com/gh_mirrors/js/jstutorial点击查看免费下载package.json是每个 Node.js 项目根目录下的核心配置文件它既声明了项目所需的全部模块依赖也承载了名称、版本、许可证等元数据并充当 npm 脚本命令的注册表。本文以 jstutorial 仓库中 package.json 文件文档 为骨架逐字段拆解其含义与用法并结合本仓库自身的 package.json 与 Gruntfile.js 给出可落地的实战示例。读完本文你将能够独立编写、生成和维护 package.json掌握npm install、npm run等命令与配置字段的协作机制并理解版本范围、脚本钩子、bin 链接等进阶用法。概述package.json 是什么每个项目的根目录下面一般都有一个package.json文件它定义了这个项目所需要的各种模块以及项目的配置信息比如名称、版本、许可证等元数据。npm install命令根据这个配置文件自动下载所需的模块也就是配置项目所需的运行和开发环境。下面是一个最简单的 package.json 文件只定义两项元数据项目名称和项目版本。{ name : xxx, version : 0.0.0, }package.json文件就是一个 JSON 对象该对象的每一个成员就是当前项目的一项设置。比如name就是项目名称version是版本遵守大版本.次要版本.小版本的格式。下面是一个更完整的 package.json 文件。{ name: Hello World, version: 0.0.1, author: 张三, description: 第一个node.js程序, keywords:[node.js,javascript], repository: { type: git, url: https://path/to/url }, license:MIT, engines: {node: 0.10.x}, bugs:{url:http://path/to/bug,email:bugexample.com}, contributors:[{name:李四,email:lisiexample.com}], scripts: { start: node index.js }, dependencies: { express: latest, mongoose: ~3.8.3, handlebars-runtime: ~1.0.12, express3-handlebars: ~0.5.0, MD5: ~1.2.0 }, devDependencies: { bower: ~1.2.8, grunt: ~0.4.1, grunt-contrib-concat: ~0.3.0, grunt-contrib-jshint: ~0.7.2, grunt-contrib-uglify: ~0.2.7, grunt-contrib-clean: ~0.5.0, browserify: 2.36.1, grunt-browserify: ~1.3.0, } }可以看到一个典型的 package.json 由三部分内容组成描述项目自身的元数据name、version、author、description、keywords、license等、声明依赖关系的字段dependencies、devDependencies、peerDependencies以及定义运行行为与入口的字段scripts、bin、main、config等。作为真实案例本仓库根目录的 package.json 就是一个完整的示例它以name: jstutorial、version: 0.5.0、description: JavaScript 标准参考教程描述自身用main: index.md指明首页入口文档通过scripts: { build: grunt, ... }将构建任务交给 Grunt并在devDependencies中列出了grunt、grunt-contrib-uglify等开发期工具。scripts 字段用 npm 统一管理命令行任务scripts指定了运行脚本命令的 npm 命令行缩写比如start指定了运行npm run start时所要执行的命令。下面的设置指定了npm run preinstall、npm run postinstall、npm run start、npm run test时所要执行的命令。scripts: { preinstall: echo here it comes!, postinstall: echo there it goes!, start: node index.js, test: tap test/*.js }npm run命令会自动在环境变量$PATH中添加node_modules/.bin目录因此scripts字段里调用命令时不用加上路径这就避免了全局安装 npm 模块。此外npm 内置了两个命令简写npm test等同于执行npm run testnpm start等同于执行npm run start。本仓库的 package.json 就体现了这个机制scripts: { build: grunt, test: echo \Error: no test specified\ exit 1 }执行npm run build时npm 会调用本地node_modules/.bin目录下的 grunt 命令而对应的 Gruntfile.js 则注册了uglify:target与cssmin:minify两个任务并通过grunt.registerTask(default, [uglify:target, cssmin:minify])将它们串联为默认任务。这是典型的配置声明 任务脚本分工模式scripts字段是入口真正的构建逻辑由 Gruntfile 承载。pre- 与 post- 钩子npm run为每条命令提供了pre-和post-两个钩子hook。以npm run lint为例执行这条命令之前npm 会先查看有没有定义prelint和postlint两个钩子如果有的话就会先执行npm run prelint然后执行npm run lint最后执行npm run postlint。如果执行过程出错就不会执行排在后面的脚本。除了用户自定义命令npm 对内置命令同样提供钩子常见的有preinstall/postinstall用户执行npm install命令时先执行 / 安装结束后执行该脚本prepublish/postpublish发布模块前 / 后执行preuninstall/postuninstall卸载模块前 / 后执行preversion/postversion更改模块版本前 / 后执行pretest/posttest运行npm test前 / 后执行prestart/poststart运行npm start前 / 后执行prestop/poststop运行npm stop前 / 后执行prerestart/postrestart运行npm restart前 / 后执行。注意不能在pre脚本之前再加pre即prepretest脚本不起作用。postinstall常用于处理从 Git 仓库拉下来的源码——比如有些源码用 TypeScript 编写需要在安装后编译转换。内部变量scripts 字段可以使用一些内部变量主要是 package.json 的各种字段。比如 package.json 的内容是{name:foo, version:1.2.5}那么变量npm_package_name的值是 foo变量npm_package_version的值是 1.2.5{ scripts:{ bundle: mkdir -p build/$npm_package_version/ } }运行npm run bundle以后将会生成build/1.2.5/子目录。关于npm run的更多用法参数传递、命令编排、npm-run-all等可进一步阅读仓库中的 npm 模块管理器文档。dependencies 与 devDependencies 字段声明依赖及其版本范围dependencies字段指定了项目运行所依赖的模块devDependencies指定项目开发所需要的模块。它们都指向一个对象该对象的各个成员分别由模块名和对应的版本要求组成表示依赖的模块及其版本范围。{ devDependencies: { browserify: ~13.0.0, karma-browserify: ~5.0.1 } }对应的版本可以加上各种限定主要有以下几种指定版本比如1.2.2遵循大版本.次要版本.小版本的格式规定安装时只安装指定版本。波浪号tilde指定版本比如~1.2.2表示安装 1.2.x 的最新版本不低于 1.2.2但是不安装 1.3.x也就是说安装时不改变大版本号和次要版本号。插入号caret指定版本比如^1.2.2表示安装 1.x.x 的最新版本不低于 1.2.2但是不安装 2.x.x也就是说安装时不改变大版本号。需要注意的是如果大版本号为 0则插入号的行为与波浪号相同这是因为此时处于开发阶段即使是次要版本号变动也可能带来程序的不兼容。latest安装最新版本。npm 采用语义版本semver管理软件包版本号为a.b.c的形式其中a是大版本号b是小版本号c是补丁号。一个软件发布的时候默认就是v1.0.0版以后发布补丁就增加最后一位数字增加新功能且不影响原有功能就增加中间的数字引入破坏向后兼容性的变化则增加第一位数字。需要注意如果大版本不到 v1.0.0即 v0.x.y时不兼容变动应修改小版本号即从v0.4.1升级到v0.5.0。对于~和^可以这样具体区分~2.2.1 // 接受2.2.1不接受2.3.0 ^2.2.1 // 接受2.2.1和2.3.0 ~2.2 // 接受2.2.0和2.2.1不接受2.3.0 ^2.2 // 接受2.2.0、2.2.1和2.3.0 ~2 // 接受2.0.0、2.1.0、2.2.0、2.2.1和2.3.0 ^2 // 接受2.0.0、2.1.0、2.2.0、2.2.1和2.3.0此外还可以使用数学运算符比如、、、或指定版本范围例如 2.1、1.0.0 - 1.2.0、 1.0.0-rc.0 1.0.1。如果使用连字号它的两端必须有空格否则会被 npm 理解成预发布的 tag。*或x则表示接受所有更新。更多语义版本规则可参考仓库中的 版本管理文档。本仓库的 package.json 正好同时展示了~与^两种写法grunt: ~0.4.2表示安装 0.4.x 系列的最新补丁版本cz-conventional-changelog: ^1.1.5表示安装 1.x.x 系列的最新版本。生成 package.jsonnpm initpackage.json 文件可以手工编写也可以使用npm init命令自动生成。$ npm init这个命令采用互动方式要求用户回答一些问题然后在当前目录生成一个基本的 package.json 文件。所有问题之中只有项目名称name和项目版本version是必填的其他都是选填的。如果使用了-f代表 force或-y代表 yes参数则跳过提问阶段直接生成一个新的 package.json 文件$ npm init -y安装依赖并写入配置有了 package.json 文件直接使用 npm install 命令就会在当前目录中安装所需要的模块。$ npm install如果一个模块不在package.json文件之中可以单独安装这个模块并使用相应的参数将其写入package.json文件之中。$ npm install express --save $ npm install express --save-dev上面代码表示单独安装 express 模块--save参数表示将该模块写入dependencies属性--save-dev表示将该模块写入devDependencies属性。这两个参数也分别可以简写为-S和-D。相关补充用法npm install --save-exact会在 package.json 中记录模块的确切版本而不是一个可选的版本范围也可以预先用npm set save-exact true全局开启这一行为。默认情况下npm install会同时安装dependencies与devDependencies中的全部模块使用--production参数或设置环境变量NODE_ENVproduction时只安装dependencies字段的模块这正是部署环境常用的做法。用npm config set save-prefix ~可以把--save/--save-dev写入的版本范围从默认的插入号^改成波浪号~即从允许小版本升级变成只允许补丁包的升级。在仓库的 express 文档 中可以看到一个手工编写的实例dependencies中写入express: 3.x随后执行npm install即可按该版本范围安装框架依赖。peerDependencies 字段为插件声明宿主版本有时你的项目和所依赖的模块都会同时依赖另一个模块但是所依赖的版本不一样。比如你的项目依赖 A 模块和 B 模块的 1.0 版而 A 模块本身又依赖 B 模块的 2.0 版。大多数情况下这不构成问题B 模块的两个版本可以并存同时运行。但是有一种情况会出现问题就是这种依赖关系将暴露给用户。最典型的场景就是插件比如 A 模块是 B 模块的插件。用户安装的 B 模块是 1.0 版本但是 A 插件只能和 2.0 版本的 B 模块一起使用。这时用户要是将 1.0 版本的 B 的实例传给 A就会出现问题。因此需要一种机制在模板安装的时候提醒用户如果 A 和 B 一起安装那么 B 必须是 2.0 模块。peerDependencies字段就是用来供插件指定其所需要的主工具的版本。{ name: chai-as-promised, peerDependencies: { chai: 1.x } }上面代码指定安装chai-as-promised模块时主程序chai必须一起安装而且chai的版本必须是1.x。如果你的项目指定的依赖是chai的 2.0 版本就会报错。注意从 npm 3.0 版开始peerDependencies不再会默认安装了——它仅作为版本兼容性约束存在npm 会在宿主项目引入版本冲突时给出警告或错误提示。bin 字段注册可执行命令bin项用来指定各个内部命令对应的可执行文件的位置。bin: { someTool: ./bin/someTool.js }上面代码指定someTool 命令对应的可执行文件为 bin 子目录下的 someTool.js。npm 会寻找这个文件在node_modules/.bin/目录下建立符号链接。在上面的例子中someTool.js 会建立符号链接node_modules/.bin/someTool。由于node_modules/.bin/目录会在运行时加入系统的 PATH 变量因此在运行 npm 时就可以不带路径直接通过命令来调用这些脚本。因此像下面这样的写法可以采用简写。scripts: { start: ./node_modules/.bin/someTool.js build } // 简写为 scripts: { start: someTool build }所有node_modules/.bin/目录下的命令都可以用npm run [命令]的格式运行。在命令行下键入npm run然后按 tab 键就会显示所有可以使用的命令直接运行npm run不带参数则会列出 scripts 属性下的全部命令及其对应的脚本内容。npm run会创建一个 Shell 执行指定的命令并临时将node_modules/.bin加入 PATH 变量这意味着本地模块可以直接运行。举例来说执行npm i eslint --save-dev后node_modules/.bin目录会生成指向 ESLint 可执行脚本的符号链接node_modules/.bin/eslint随后就能在scripts里不带路径地写lint: eslint .。这正是依赖本地安装 bin 注册组合出的免全局安装开发流程。main 字段指定模块入口文件main字段指定了加载的入口文件require(moduleName)就会加载这个文件。这个字段的默认值是模块根目录下面的index.js。以本仓库的 package.json 为例main: index.md表示该教程项目的入口文档是根目录的 index.md。而对于普通的 Node 模块来说main字段的解析规则可以在仓库的 模块加载文档 中看到完整说明当require发现参数字符串指向一个目录以后会自动查看该目录的 package.json 文件然后加载main字段指定的入口文件如果 package.json 没有main字段或者根本就没有 package.json 文件则会加载该目录下的index.js文件或index.node文件。// package.json { name : some-library, main : ./lib/some-library.js }config 字段为脚本提供可配置的环境变量config字段用于添加命令行的环境变量。下面是一个package.json文件。{ name : foo, config : { port : 8080 }, scripts : { start : node server.js } }然后在server.js脚本就可以引用config字段的值。http .createServer(...) .listen(process.env.npm_package_config_port)用户执行npm run start命令时这个脚本就可以得到值。$ npm run start用户可以改变这个值。$ npm config set foo:port 80注意这里的命名规则config字段中的键会以npm_package_config_为前缀暴露为环境变量即config.port对应process.env.npm_package_config_port。这使config成为在 npm 脚本与应用程序之间传递可调参数的标准通道。本仓库的 package.json 也使用了config字段——它把 commitizen 的配置路径放在config.commitizen.path中供相关工具读取。其他常用字段browser 字段browser 指定该模板供浏览器使用的版本。Browserify 这样的浏览器打包工具通过它就知道该打包那个文件。browser: { tipso: ./node_modules/tipso/src/tipso.js },engines 字段engines字段指明了该模块运行的平台比如 Node 的某个版本或者浏览器。{ engines : { node : 0.10.3 0.12 } }该字段也可以指定适用的npm版本。{ engines : { npm : ~1.0.20 } }man 字段man用来指定当前模块的 man 文档的位置。man :[ ./doc/calc.1 ]preferGlobal 字段preferGlobal的值是布尔值表示当用户不将该模块安装为全局模块时即不用--global参数要不要显示警告表示该模块的本意就是安装为全局模块。它适用于命令行工具类的模块——这类模块的本意就是安装为全局命令而本地安装会削弱其价值。style 字段style指定供浏览器使用时样式文件所在的位置。样式文件打包工具 parcelify通过它知道样式文件的打包位置。style: [ ./node_modules/tipso/src/tipso.css ]小结package.json是 Node.js 项目的配置中枢元数据字段name、version、license、author等描述项目身份依赖字段dependencies、devDependencies、peerDependencies声明模块与版本范围行为字段scripts、bin、main、config则定义命令入口与运行时配置。掌握这些字段后配合npm init生成配置、npm install --save/--save-dev维护依赖、npm run执行脚本就能构建出可维护、可部署、可发布的标准 Node.js 项目。仓库中的 package.json 文件文档 与 npm 模块管理器文档 是进一步深入学习的参考入口。赞分享教程文档【免费下载链接】jstutorialJavascript tutorial book项目地址https://gitcode.com/gh_mirrors/js/jstutorial点击查看免费下载相关推荐Ciao高级配置如何自定义检查间隔和通知模板Ciao高级配置如何自定义检查间隔和通知模板 Ciao是一款强大的HTTP监控工具能够帮助您实时跟踪网站和服务的运行状态。通过自定义检查间隔和通知模板您可FilePizza依赖管理package.json完全解析FilePizza依赖管理package.json完全解析 概述 在现代前端开发中 package.json 文件扮演着项目身份证和操作手册的双重角ChainList依赖管理package.json配置深度解析ChainList依赖管理package.json配置深度解析 概述 ChainList作为一个多链RPCRemote Procedure Call远程过上一篇Steam成就管理器完全指南三步掌握所有游戏成就的终极方案下一篇LocalAI 的 Model Context Protocol (MCP) 集成从 YAML 配置到服务端/浏览器双端 Agent 工具循环创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考