前端框架使用vue-cli（ 第一层：依赖与环境层）

第一层：依赖与环境层

1. node_modules
2. package.json
3. package-lock.json

介绍：

这个文章主要是说明vue-cli的，对于nodejs的环境安装，以及npm的使用配置，就不多说了

我们将在有nodejs的环境

使用npm安装好对应的依赖

依赖安装的具体位置，将在node_modules这个包下

像pom一样，展示依赖的具体的信息，讲展示在

package.json 与 package-lock.json 详解

---

一、package.json

文件作用

项目的"身份证"+"依赖清单"+"脚本入口"，声明项目需要什么、怎么运行。

---

完整示例及逐行解释

{
  // ========== 1. 项目基本信息 ==========
  "name": "my-vue-project",
  // 项目名称，唯一标识（发布到 npm 时必需）
  
  "version": "1.0.0",
  // 版本号，遵循语义化版本（major.minor.patch）
  // 1.0.0 → 1（大版本/不兼容改动）.0（新功能/兼容）.0（bug修复）
  
  "description": "这是一个Vue项目",
  // 项目描述，npm 搜索时显示
  
  "author": "张三 <zhangsan@example.com>",
  // 作者信息
  
  "license": "MIT",
  // 开源协议类型
  
  "private": true,
  // 防止误发布到 npm 仓库（企业项目一般都是 true）
  
  // ========== 2. 工程命令 ==========
  "scripts": {
    "serve": "vue-cli-service serve",
    // npm run serve → 启动开发服务器
    
    "build": "vue-cli-service build",
    // npm run build → 打包生产环境代码
    
    "lint": "vue-cli-service lint",
    // npm run lint → 检查代码规范
    
    "test": "jest",
    // npm run test → 运行测试
    
    "dev": "npm run serve"
    // 别名，可以自定义任何命令
  },
  
  // ========== 3. 生产依赖 ==========
  "dependencies": {
    "vue": "^3.2.0",
    // 上线后也必须有的依赖
    // ^3.2.0 表示 3.2.0 ≤ 版本 < 4.0.0
    
    "axios": "^1.5.0",
    // HTTP 请求库
    
    "element-plus": "^2.4.0",
    // UI 组件库
    
    "vue-router": "^4.2.0",
    // 路由
    
    "pinia": "^2.1.0"
    // 状态管理
  },
  
  // ========== 4. 开发依赖 ==========
  "devDependencies": {
    "@vue/cli-service": "^5.0.0",
    // Vue CLI 构建工具，只在开发时需要
    
    "eslint": "^8.0.0",
    // 代码检查工具
    
    "prettier": "^3.0.0",
    // 代码格式化工具
    
    "jest": "^29.0.0"
    // 测试框架，只在开发时需要
  },
  
  // ========== 5. 版本范围配置 ==========
  "engines": {
    "node": ">=16.0.0",
    // 要求 Node.js 版本 ≥ 16
    "npm": ">=8.0.0"
    // 要求 npm 版本 ≥ 8
  },
  
  // ========== 6. 入口文件 ==========
  "main": "src/main.js",
  // 模块入口（Node.js 环境使用）
  
  "module": "dist/index.js",
  // ES Module 入口（打包工具使用）
  
  // ========== 7. 发布配置 ==========
  "files": [
    "dist",
    "src",
    "*.js"
  ],
  // npm publish 时包含哪些文件
  
  "keywords": ["vue", "admin", "dashboard"],
  // 关键词，方便 npm 搜索
  
  "repository": {
    "type": "git",
    "url": "https://github.com/xxx/my-project.git"
  },
  // 代码仓库地址
  
  "bugs": {
    "url": "https://github.com/xxx/my-project/issues"
  },
  // issue 反馈地址
  
  "homepage": "https://github.com/xxx/my-project#readme"
  // 项目主页
}

---

dependencies vs devDependencies 核心区别

	dependencies	devDependencies
何时需要	运行时	开发/构建时
典型包	vue、axios、element-ui	webpack、eslint、jest
生产打包	✅ 会打包进去	❌ 不会打包进去
举例	Vue 框架在浏览器里需要运行	ESLint 只在写代码时检查，浏览器不需要

npm install vue              → 保存到 dependencies
npm install -D webpack       → 保存到 devDependencies
npm install --save-dev jest  → 同上

---

版本符号详解

{
  "axios": "1.5.0",        // 精确版本，只装 1.5.0
  "lodash": "^4.17.0",     // 兼容：4.17.0 ≤ 版本 < 5.0.0
  "vue": "~3.2.0",         // 更严格：3.2.0 ≤ 版本 < 3.3.0
  "react": ">=17.0.0",     // 大于等于 17.0.0
  "express": "4.x",        // 主版本固定：4.x.x 最新
  "webpack": "*"           // 任意版本（不推荐）
}

^ 和 ~ 的区别

版本号：major.minor.patch（主版本.次版本.补丁版本）

^1.2.3
  允许: 1.2.3, 1.2.4, 1.3.0, 1.9.9
  不允许: 2.0.0（主版本变了）

~1.2.3
  允许: 1.2.3, 1.2.4, 1.2.9
  不允许: 1.3.0（次版本变了），2.0.0

---

二、package-lock.json

文件作用

精确锁定依赖树中每一个包的版本和下载地址，保证每次安装结果完全相同。

---

完整示例及逐行解释

{
  // ========== 1. 文件元信息 ==========
  "name": "my-vue-project",
  // 与 package.json 同名
  
  "version": "1.0.0",
  // 与 package.json 同版本
  
  "lockfileVersion": 3,
  // lock 文件格式版本（npm v7+ 使用 version 3）
  
  // ========== 2. 整体依赖树 ==========
  "packages": {
    // node_modules 中每个包的信息
    
    "": {
      // 空字符串代表项目根目录
      "name": "my-vue-project",
      "version": "1.0.0",
      "dependencies": {
        "vue": "^3.2.0",
        "axios": "^1.5.0"
      },
      "devDependencies": {
        "@vue/cli-service": "^5.0.0"
      }
    },
    
    // ========== 3. 具体依赖包信息 ==========
    "node_modules/axios": {
      "version": "1.5.0",
      // 精确安装的版本号
      
      "resolved": "https://registry.npmmirror.com/axios/-/axios-1.5.0.tgz",
      // 从哪个地址下载的（镜像源地址）
      
      "integrity": "sha512-pN/7nO8I4S3JzZEvfD4F9EHG8b0Z3KxnYX5rYkPcAUlT4QcE9v5DHhUW20wR1e5/2kZzWwCT7WiuGksKQ1fog==",
      // 文件完整性校验（SHA512哈希），防止下载文件被篡改
      
      "peerDependencies": {},
      // 对等依赖（如果有要求）
      
      "engines": {
        "node": ">=12.0.0"
      }
      // 要求的环境版本
    },
    
    "node_modules/axios/node_modules/follow-redirects": {
      // axios 依赖的 follow-redirects（嵌套依赖）
      "version": "1.15.3",
      "resolved": "https://registry.npmmirror.com/follow-redirects/-/follow-redirects-1.15.3.tgz",
      "integrity": "sha512-1VzOtuEM8pC9SFU1E+8KfTjZyMztRsgEfwQl44z8A25uy13jSzTj6dyK2Df52iV0vgHCfBwLhDWevLn95w5v6Q=="
    },
    
    "node_modules/vue": {
      "version": "3.2.47",
      "resolved": "https://registry.npmmirror.com/vue/-/vue-3.2.47.tgz",
      "integrity": "sha512-60188y/9Dc9WVrAZeUVSDxRQOZ+z+y5nO2ts9jWXSTkMvHavj5EeMGlBEo/9WgU4D/mpB/2y1cXpp+rQ4nU3A==",
      "dependencies": {
        "@vue/compiler-dom": "3.2.47",
        "@vue/runtime-dom": "3.2.47"
        // vue 依赖的其他包也会被锁定
      }
    },
    
    "node_modules/@vue/compiler-dom": {
      "version": "3.2.47",
      "resolved": "https://registry.npmmirror.com/@vue/compiler-dom/-/compiler-dom-3.2.47.tgz",
      "dependencies": {
        "@vue/shared": "3.2.47"
      }
    },
    
    "node_modules/@vue/runtime-dom": {
      "version": "3.2.47",
      "dependencies": {
        "@vue/runtime-core": "3.2.47",
        "@vue/shared": "3.2.47"
      }
    },
    
    "node_modules/eslint": {
      // devDependencies 中的包也会被锁定
      "version": "8.55.0",
      "resolved": "https://registry.npmmirror.com/eslint/-/eslint-8.55.0.tgz",
      "dev": true
      // dev: true 标记这是开发依赖
    }
  },
  
  // ========== 4. 依赖关系（旧版格式，兼容保留）==========
  "dependencies": {
    // 这是 npm v6 及之前的格式，新版也会保留用于兼容
    "axios": {
      "version": "1.5.0",
      "resolved": "https://registry.npmmirror.com/axios/-/axios-1.5.0.tgz",
      "integrity": "sha512-xxx...",
      "requires": {
        "follow-redirects": "^1.15.0"
      }
    }
  }
}

---

三、两个文件解决的核心问题

问题1：版本漂移

场景

package.json: "axios": "^1.5.0"

2024-01-01 安装: axios@1.5.0
2024-03-01 安装: axios@1.6.0（新版本）

张三（1月安装）: 1.5.0 ✅ 正常运行
李四（3月安装）: 1.6.0 ❌ 出现 bug（新版本有 breaking change）

lock 文件解决

package-lock.json 锁定: axios@1.5.0

张三 → npm ci → 安装 1.5.0 ✅
李四 → npm ci → 安装 1.5.0 ✅

---

问题2：间接依赖失控

场景

你只写了: dependencies: { "axios": "^1.5.0" }

但 axios 自己依赖了 "follow-redirects": "^1.0.0"

2024-01-01 安装: follow-redirects@1.0.0 ✅ 能用
2025-01-01 安装: follow-redirects@2.0.0 ❌ API 变化，axios 不兼容

lock 文件解决

package-lock.json 锁定了整个依赖树:

axios@1.5.0
  └── follow-redirects@1.15.3（特定版本）

间接依赖也被锁定，不会乱变

---

问题3：下载源不一致

场景

张三用官方源: registry.npmjs.org
李四用淘宝源: registry.npmmirror.com
有时镜像同步有延迟，两个源同一时刻版本可能不同

lock 文件解决

package-lock.json 记录了具体的 resolved 下载地址

"resolved": "https://registry.npmmirror.com/axios/-/axios-1.5.0.tgz"

所有人都从同一个地址下载同一份文件

---

问题4：文件被篡改风险

lock 文件解决

package-lock.json 记录了 integrity 哈希值

"integrity": "sha512-pN/7nO8I4S3JzZEvfD4F9EHG8b0Z3KxnYX5rYkPcAUlT4QcE9v5DHhUW20wR1e5/2kZzWwCT7WiuGksKQ1fog=="

下载后校验哈希，如果文件被篡改 → 安装失败

---

四、什么时候使用哪个命令

命令	读取文件	行为	适用场景
npm install	package.json + lock	按 lock 安装（如果 lock 存在），否则按 package.json 解析并生成 lock	日常开发（首次或不确定时）
npm ci	lock 文件（强制需要）	严格按 lock 安装，更快更准	CI/CD、团队协作（保证环境一致）
npm update	package.json	按 package.json 的范围升级到最新匹配版本，更新 lock	想要升级依赖时
npm install axios@1.6.0	package.json + lock	安装指定版本，同时更新两个文件	手动升级某个包

---

五、团队协作最佳实践

✅ 必须做

1. package-lock.json 提交到 git
2. 使用 npm ci 代替 npm install（CI 环境）
3. 所有人使用相同版本的 npm

❌ 禁止做

1. 把 package-lock.json 加入 .gitignore
2. 手动编辑 package-lock.json
3. 混合使用 npm 和 yarn（各自的 lock 文件不同）

---

六、一句话总结

package.json      = "我想要什么"（声明 + 范围）
package-lock.json = "我实际用了什么"（精确锁定 + 完整性校验）

两者配合 = 团队成员 + CI 服务器 + 生产环境，装出来的依赖【完全一样】

---