package.json 配置详解：项目的身份证

前言

想象一下，如果你的项目是一个人，那么 package.json 就是这个人的身份证。它记录了项目的基本信息、依赖关系、运行脚本等所有重要信息。

没有 package.json，你的项目就像一个没有身份的人，无法被 npm 识别和管理。而一个配置完善的 package.json，则能让你的项目在团队协作、部署发布、依赖管理等方面游刃有余。

本节你将学到

📋 package.json 的核心字段和配置方法
🔄 dependencies vs devDependencies 的正确使用
🚀 项目元数据的最佳实践
⚡ 自动化配置和依赖管理技巧
🎯 如何编写规范的包描述信息

项目面临的核心问题

在深入 package.json 之前，让我们先看看它要解决的实际问题：

问题 1：项目如何移植和还原？

bash 复制代码

# 传统方式的问题
my-project/
├── src/
├── node_modules/     # 几万个文件，几百MB
└── index.js

# 如何把项目给同事？
# 压缩包太大，上传下载都困难
# 删除 node_modules 后，同事如何知道需要安装哪些包？

问题 2：如何区分开发依赖和生产依赖？

javascript 复制代码

// 开发时需要的工具
const jest = require('jest');        // 测试框架
const prettier = require('prettier'); // 代码格式化

// 生产环境需要的库
const express = require('express');   // Web 框架
const lodash = require('lodash');     // 工具库

// 如何告诉部署系统：只安装生产依赖，不要安装开发工具？

问题 3：如何描述项目信息？

bash 复制代码

# 项目的基本信息
- 项目叫什么名字？
- 当前是什么版本？
- 作者是谁？
- 入口文件在哪里？
- 如何运行和测试？

package.json 就是为了解决这些问题而生的！

创建 package.json

交互式创建

bash 复制代码

# 创建新项目
mkdir my-calculator
cd my-calculator

# 交互式初始化
npm init

npm 会逐步询问项目信息：

bash 复制代码

package name: (my-calculator) 
version: (1.0.0) 
description: 一个简单的数学计算器
entry point: (index.js) 
test command: npm test
git repository: https://github.com/username/my-calculator
keywords: calculator, math, add
author: Your Name <your.email@example.com>
license: (ISC) MIT

快速创建

bash 复制代码

# 使用默认配置快速创建
npm init -y
# 或
npm init --yes

生成的默认 package.json：

json 复制代码

{
  "name": "my-calculator",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

核心字段详解

基本信息字段

name - 项目名称

json 复制代码

{
  "name": "simple-math-calculator"
}

命名规则：

必须是英文单词字符
支持连接符 - 和下划线 _
不能包含空格和特殊字符
建议使用小写字母

bash 复制代码

# ✅ 正确的命名
"simple-calculator"
"math-utils"
"my_awesome_lib"

# ❌ 错误的命名
"Simple Calculator"    # 包含空格
"math@utils"          # 包含特殊字符
"中文名称"             # 包含中文

version - 版本号

json 复制代码

{
  "version": "1.2.3"
}

语义化版本规范（SemVer）：

复制代码

主版本号.次版本号.补丁版本号
   1   .   2   .   3

主版本号（Major）：重大变化，可能不兼容旧版本
- 新增重要功能
- 大量 API 变更
- 技术架构重构
次版本号（Minor）：小功能更新，向后兼容
- 新增小功能
- 新增辅助 API
- 性能优化
补丁版本号（Patch）：bug 修复，向后兼容
- 修复 bug
- 局部优化
- 文档更新

description - 项目描述

json 复制代码

{
  "description": "一个简单易用的数学计算库，提供基础运算功能"
}

好的描述特点：

简洁明了，一句话说清楚项目用途
包含关键功能点
便于搜索和理解

main - 入口文件

json 复制代码

{
  "main": "index.js"
}

javascript 复制代码

// index.js - 项目入口文件
function add(a, b) {
  return a + b;
}

function subtract(a, b) {
  return a - b;
}

module.exports = {
  add,
  subtract
};

当其他人使用 require('your-package') 时，实际加载的就是 main 字段指定的文件。

author - 作者信息

json 复制代码

{
  "author": "Zhang San <zhangsan@example.com>"
}

标准格式：

xml 复制代码

姓名 <邮箱>

注意事项：

必须是有效的 npm 账户名
邮箱格式要正确
发布包时会验证作者信息

keywords - 搜索关键词

json 复制代码

{
  "keywords": ["calculator", "math", "add", "subtract", "utility"]
}

帮助其他开发者通过关键词搜索到你的包：

bash 复制代码

npm search calculator
npm search math utility

repository - 代码仓库

json 复制代码

{
  "repository": {
    "type": "git",
    "url": "https://github.com/username/my-calculator.git"
  }
}

homepage - 项目主页

json 复制代码

{
  "homepage": "https://github.com/username/my-calculator#readme"
}

license - 开源协议

json 复制代码

{
  "license": "MIT"
}

常见开源协议：

MIT：最宽松，允许商用
Apache-2.0：允许商用，需保留版权声明
GPL-3.0：开源传染性，衍生作品必须开源
ISC：类似 MIT，更简洁

依赖管理：dependencies vs devDependencies

dependencies - 生产依赖

json 复制代码

{
  "dependencies": {
    "lodash": "^4.17.21",
    "express": "^4.18.2"
  }
}

生产依赖的特点：

项目运行时必需的包
会被部署到生产环境
用户安装你的包时也会安装这些依赖

javascript 复制代码

// 生产代码中使用
const _ = require('lodash');
const express = require('express');

function processData(data) {
  return _.uniq(data); // 生产环境需要 lodash
}

devDependencies - 开发依赖

json 复制代码

{
  "devDependencies": {
    "jest": "^29.0.0",
    "prettier": "^2.8.0",
    "eslint": "^8.0.0"
  }
}

开发依赖的特点：

仅开发时需要的工具
不会部署到生产环境
用户安装你的包时不会安装这些依赖

javascript 复制代码

// 仅在开发时使用
// jest 用于测试
// prettier 用于代码格式化
// eslint 用于代码检查

安装命令对比

bash 复制代码

# 安装到生产依赖（默认行为）
npm install lodash
npm install --save lodash     # 显式指定

# 安装到开发依赖
npm install --save-dev jest
npm install -D jest           # 简写

# 安装所有依赖
npm install                   # 开发 + 生产依赖

# 仅安装生产依赖（生产环境部署时使用）
npm install --production
npm install --only=production

实际使用场景

json 复制代码

{
  "name": "math-calculator",
  "dependencies": {
    "decimal.js": "^10.4.0"      // 生产需要
  },
  "devDependencies": {
    "jest": "^29.0.0",           // 测试框架
    "prettier": "^2.8.0",        // 代码格式化
    "eslint": "^8.0.0",          // 代码检查
    "@types/node": "^18.0.0"     // TypeScript 类型定义
  }
}

实战练习

练习 1：创建完整的 package.json

bash 复制代码

# 创建练习项目
mkdir calculator-practice
cd calculator-practice

# 初始化项目
npm init -y

# 安装生产依赖
npm install decimal.js

# 安装开发依赖
npm install -D jest prettier

# 查看生成的 package.json
cat package.json

练习 2：编写入口文件

javascript 复制代码

// index.js
const Decimal = require('decimal.js');

function add(a, b) {
  return new Decimal(a).plus(b).toNumber();
}

function subtract(a, b) {
  return new Decimal(a).minus(b).toNumber();
}

module.exports = {
  add,
  subtract
};

练习 3：测试项目配置

javascript 复制代码

// test.js
const { add, subtract } = require('./index');

console.log('2 + 3 =', add(2, 3));           // 5
console.log('0.1 + 0.2 =', add(0.1, 0.2));   // 0.3 (精确计算)
console.log('5 - 3 =', subtract(5, 3));      // 2

bash 复制代码

# 运行测试
node test.js

本章小结

🎯 核心概念

package.json：项目的身份证和配置中心
基本信息：name, version, description, author 等
依赖分类：dependencies（生产）vs devDependencies（开发）
语义版本：主.次.补丁的版本规范

🔧 实用技能

使用 npm init 创建配置文件
正确区分和管理生产依赖与开发依赖
编写规范的项目元数据信息
配置合适的入口文件和关键词

💡 最佳实践

使用语义化版本号管理项目版本
合理分类依赖，优化生产环境部署
编写清晰的项目描述和关键词
提供完整的作者和仓库信息

下一章预告

在下一章《包的使用：模块引用与路径解析的艺术》中，我们将深入学习：

CommonJS 模块系统的工作原理
Node.js 的模块查找算法
相对路径与绝对路径的使用场景
子目录中模块引用的最佳实践

配置好了 package.json，接下来就要学会如何正确使用这些包了。让我们继续探索 npm 的强大功能！

📚 延伸阅读

package.json 官方文档

语义化版本规范

开源协议选择指南