从新认识 package.json

前言 🤔

• 在每一个项目的根目录下面，通常都会有一个 package.json 文件，其定义了运行项目所须要的各类依赖和项目的配置信息（如名称、版本、许可证等元数据）。
• 大多数人对 package.json 文件的了解，仅停留在：
  • 项目名称、项目构建版本、许可证的定义；
  • 依赖定义（包括 dependencies 字段，devDependencies 字段）；
  • 使用scripts字段指定运行脚本命令的 npm 命令行缩写。
• 其实，package.json 的做用远不止于此，咱们能够经过新增配置项实现更强大的功能，下面将带你从新认识 package.json。

由简入繁，丰富项目的 package.json

简单版的 package.json

• 当咱们新建一个名称为 my-test 的项目时，使用 yarn init -y 或 npm init -y 命令后，在项目目录下会新增一个 package.json文件，内容以下：

{
  "name": "my-test", # 项目名称
  "version": "1.0.0", # 项目版本（格式：大版本.次要版本.小版本）
  "description": "", # 项目描述
  "main": "index.js", # 入口文件
  "scripts": { # 指定运行脚本命令的 npm 命令行缩写
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [], # 关键词
  "author": "", # 做者
  "license": "ISC" # 许可证
}
复制代码

• 能够看到，package.json 文件的内容是一个 JSON 对象，对象的每个成员就是当前项目的一项配置。

安装项目依赖（dependencies & devDependencies）

• dependencies字段指定了项目运行所依赖的模块（生产环境使用），如 antd、 react、 moment等插件库：
  • 它们是咱们生产环境所须要的依赖项，在把项目做为一个 npm 包的时候，用户安装 npm 包时只会安装 dependencies 里面的依赖。
• devDependencies 字段指定了项目开发所须要的模块（开发环境使用），如 webpack、typescript、babel等：
  • 在代码打包提交线上时，咱们并不须要这些工具，因此咱们将它放入 devDependencies 中。
• 若是一个模块不在 package.json 文件之中，咱们能够单独安装这个模块，并使用相应的参数，将其写入 dependencies 字段/ devDependencies 字段中：

# 使用 npm
npm install <package...> --save # 写入 dependencies 属性
npm install <package...> --save-dev # 写入 devDependencies 属性

# 使用 yarn
yarn add <package...> # 写入 dependencies 属性
yarn add <package...> --dev # 写入 devDependencies 属性
复制代码

• 有了 package.json 文件，开发直接使用 npm install / yarn install 命令，就会在当前目录中自动安装所须要的模块，安装完成项目所需的运行和开发环境就配置好了。

简化终端命令（scripts）

• scripts 字段是 package.json 中的一种元数据功能，它接受一个对象，对象的属性为能够经过 npm run 运行的脚本，值为实际运行的命令（一般是终端命令），如：

"scripts": {
  "start": "node index.js"
},
复制代码

• 将终端命令放入 scripts 字段，既能够记录它们又能够实现轻松重用。

定义项目入口（main）

• main 字段是 package.json 中的另外一种元数据功能，它能够用来指定加载的入口文件。假如你的项目是一个 npm 包，当用户安装你的包后，require('my-module') 返回的是 main 字段中所列出文件的 module.exports 属性。
• 当不指定main 字段时，默认值是模块根目录下面的index.js 文件。

指定项目 node 版本（engines）

• 有时候，新拉一个项目的时候，因为和其余开发使用的 node 版本不一样，致使会出现不少奇奇怪怪的问题（如某些依赖安装报错、依赖安装完项目跑步起来等）。

  

• 为了实现项目开箱即用的伟大理想，这时候可使用 package.json 的 engines 字段来指定项目 node 版本：

"engines": {
   "node": ">= 8.16.0"
},
复制代码

• 该字段也能够指定适用的 npm 版本：

"engines": {
   "npm": ">= 6.9.0"
 },
复制代码

• 须要注意的是，engines属性仅起到一个说明的做用，当用户版本不符合指定值时也不影响依赖的安装。

自定义命令（bin）

• 用过 vue-cli，create-react-app等脚手架的朋友们，不知道大家有没有好奇过，为何安装这些脚手架后，就可使用相似 vue create/create-react-app之类的命令，其实这和 package.json 中的 bin 字段有关。
• bin 字段用来指定各个内部命令对应的可执行文件的位置。当package.json 提供了 bin 字段后，即至关于作了一个命令名和本地文件名的映射。
• 当用户安装带有 bin 字段的包时，
  • 若是是全局安装，npm 将会使用符号连接把这些文件连接到/usr/local/node_modules/.bin/；
  • 若是是本地安装，会连接到./node_modules/.bin/。
• 举个 🌰，若是要使用 my-app-cli 做为命令时，能够配置如下 bin 字段：

"bin": {
  "my-app-cli": "./bin/cli.js"
}
复制代码

• 上面代码指定，my-app-cli 命令对应的可执行文件为 bin 子目录下的 cli.js，所以在安装了 my-app-cli 包的项目中，就能够很方便地利用 npm执行脚本：

"scripts": {
  start: 'node node_modules/.bin/my-app-cli'
}
复制代码

• 咦，怎么看起来和 vue create/create-react-app之类的命令不太像？缘由：
  • 当须要 node 环境时就须要加上 node 前缀
  • 若是加上 node 前缀，就须要指定 my-app-cli 的路径 -> node_modules/.bin，不然 node my-app-cli会去查找当前路径下的 my-app-cli.js，这样确定是不对。
• 若要实现像 vue create/create-react-app之类的命令同样简便的方式，则能够在上文提到的 bin 子目录下可执行文件cli.js 中的第一行写入如下命令：

#!/usr/bin/env node
复制代码

• 这行命令的做用是告诉系统用 node 解析，这样命令就能够简写成 my-app-cli 了。

React 项目相关

设置应用根路径（homepage）

• 当咱们使用 create-react-app 脚手架搭建的 React 项目，默认是使用内置的 webpack 配置，当package.json 中不配置 homepage 属性时，build 打包以后的文件资源应用路径默认是 /，以下图：

  

• 通常来讲，咱们打包的静态资源会部署在 CDN 上，为了让咱们的应用知道去哪里加载资源，则须要咱们设置一个根路径，这时能够经过 package.json 中的 homepage 字段设置应用的根路径。
• 当咱们设置了 homepage 属性后：

{
  "homepage": "https://xxxx.cdn/my-project",
}
复制代码

• 打包后的资源路径就会加上 homepage 的地址：

  

开发环境解决跨域问题（proxy）

• 在作先后端分离的项目的时候，调用接口时则会遇到跨域的问题，当在开发环境中时，能够经过配置 package.json 中的 proxy 来解决跨域问题，配置以下：

{
  "proxy": "http://localhost:4000"  // 配置你要请求的服务器地址
}
复制代码

• 注意，当 create-react-app 的版本高于 2.0 版本的时候在 package.json 中只能配置 string 类型，这意味着若是要使用 package.json 来解决跨域问题，则只能代理一个服务器地址。
• 若是要代理多个服务器地址时，则须要安装 http-proxy-middleware ，在 src 目录下新建 setupProxy.js ：

const proxy = require("http-proxy-middleware");
 
module.exports = function(app) {
  app.use(
    proxy("/base", {
      target: "http://localhost:4000",
      changeOrigin: true
    })
  );
  app.use(
    proxy("/fans", {
      target: "http://localhost:5000",
      changeOrigin: true
    })
  );
};
复制代码

根据开发环境采用不一样的全局变量值（自定义字段）

• 假设有这么一个组件，当组件被点击时，在开发环境时是跳转测试环境的 sentry 地址，在正式环境时则跳转正式环境的 sentry 地址。
• 首先，经过配置前面提到的 scripts 字段，实现环境变量（NODE_ENV）的设置：

"scripts": {
  "start": "NODE_ENV=development node scripts/start.js",
  "build": "NODE_ENV=production node scripts/build.js",
},
复制代码

• 项目启动起来后，在代码中咱们能够经过 process.env.NODE_ENV 访问到 NODE_ENV 的值。

方案一

• 咱们能够在组件中写相似如下的判断代码，根据不一样环境给 sentryUrl 设置不一样的值：

let sentryUrl;
if (process.env.NODE_ENV === 'development') {
    sentryUrl = 'test-sentry.xxx.com';
} else {
    sentryUrl = 'sentry.xxx.com';
}
复制代码

• 这么作好像没毛病，可是深刻一想，若是有多个组件，要根据不一样的环境使用不一样的服务（多种服务）地址，若是按照上面的写法，项目中将存在许多重复的判断代码，且当服务地址发生变化时，包含这些服务地址的组件都须要相应的作改动，这样明显是不合理的。

  

方案二

• 解决方案：相关服务的地址配置在 package.json中，同时修改项目的 webpack 配置。
• 注：修改项目的 webpack 配置须要 eject 项目的 webpack 配置（更多细节可阅读 👉：react + typescript 项目的定制化过程）。
• 在项目根目录下使用 yarn eject 成功 eject 出配置后，能够发现项目目录的变化以下：

  

• 若是须要定制化项目，通常就是在 config 目录下对默认的 webpack 配置进行修改，在这里咱们须要关注 config/path.js 和 config/env.js 两个文件：
  • env.js 的主要目的在于读取 env 配置文件并将 env 的配置信息给到全局变量 process.env ；
  • path.js 的主要目的在于为项目提供各类路径，包括构建路径、 public 路径等。
• 因为本文的重点不是学习 webpack 配置，这里仅介绍如何实现【根据开发环境采用不一样的全局变量值】的功能。
• 首先，须要在 package.json 中配置如下内容：

"scripts": {
  "start": "NODE_ENV=development node scripts/start.js",
  "build": "NODE_ENV=production node scripts/build.js",
},
"sentryPath": {
  "dev": "https://test-sentry.xxx.com",
  "prod": "https://sentry.xxx.com"
 }
复制代码

• 而后，修改 path.js 文件，内容以下：

// 重写 getPublicUrl 方法
const getPublicUrl = (appPackageJson, pathName) => {
  let path;
  switch (process.env.DEPLOY_ENV) {
    case 'development':
      path = require(appPackageJson)[pathName].dev;
      break;
    case 'production':
      path = require(appPackageJson)[pathName].prod;
      break;
    default:
      path = envPublicUrl || require(appPackageJson).homepage;
  }
  return path;
}

// 新增 getSentryPath 方法
const getSentryPath = (appPackageJson) => {
  return getPublicUrl(appPackageJson, 'sentryPath');
}

// config after eject: we're in ./config/ module.exports = { ..., sentryUrl: getSentryPath(resolveApp('package.json')), // 新增 }; 复制代码

• 最后，修改 env.js 文件，内容以下：

// 修改 getClientEnvironment 方法
function getClientEnvironment(publicUrl) {
  const raw = Object.keys(process.env)
    .filter(key => REACT_APP.test(key))
    .reduce(
      (env, key) => {
        ...
      },
      {
        NODE_ENV: process.env.NODE_ENV || 'development',
        PUBLIC_URL: publicUrl,
        SENTRY_URL: paths.sentryUrl // 新增
      }
    );

  const stringified = {
    ...
  };
  return { raw, stringified };
}
复制代码

• 经过上面的配置，咱们就能够在组件中经过 process.env.SENTRY_URL 获取到 sentry 服务的地址了，虽然看起来比方案一繁琐，可是这种收益是长期的，如要新增一个 sonarqube 服务，同理实现便可，经过使用 package.json 也能够清楚的看到当前服务在不一样环境下使用的地址。

总结 👀

• 本文介绍了 package.json 的多种常见的配置字段及做用，并经过例子加深你们对 package.json这些字段的理解。
• 除了一些经常使用字段，还介绍了在React 项目中 package.json 文件能实现的一些功能进行介绍。

以上内容若有遗漏错误，欢迎留言 ✍️指出，一块儿进步💪💪💪

若是以为本文对你有帮助，🏀🏀留下你宝贵的 👍

参考资料 📖

1. Creating a package.json file
2. package.json bin的做用
3. 在开发环境中代理 API 请求
4. react + typescript 项目的定制化过程
5. React学习笔记