模块、包与依赖管理

学习目标

这一课把代码从「一个文件」推进到「一个项目」：用模块（module，通过 export/import 拆分复用的代码单元）拆分功能，读懂 package.json 与依赖锁文件，并在干净目录独立跑通一次安装和启动。读完你应该能看懂一个前端项目的「说明书」，也能说出为什么同样的 package.json 会装出不同的结果。

问题场景

你从同学那里拷来一个课程表项目，只拷了 src 目录，npm run dev 直接报错「找不到脚本」；补上 package.json 之后又发现他装的依赖版本和你不一样，行为有细微差异。项目能不能在别人机器上复现，取决于「项目自述文件」配没配齐——这一课就把这件事弄明白。

核心解释

模块化的两个关键字：

// utils/format.js —— 命名导出：一个文件可以多个，按名字导入
export function formatHours(h) {
  return h + ' 小时';
}

// utils/price.js —— 默认导出：一个文件最多一个，导入时可任意命名
export default function formatPrice(n) {
  return '¥' + n.toFixed(2);
}

import formatPrice, { formatHours } from './utils/format.js';
// formatPrice 对应默认导出；formatHours 必须与命名导出同名

浏览器原生支持 ES 模块，页面里用 <script type="module" src="..."> 引入；Node.js 需要 .mjs 后缀，或在 package.json 里写 "type": "module"。

package.json 是项目说明书，最常读的三段：

{
  "scripts": { "dev": "next dev", "build": "next build" },
  "dependencies": { "react": "^19.0.0" },
  "devDependencies": { "typescript": "^5.0.0" }
}

• scripts：npm run dev 实际执行的就是这里的命令；
• dependencies：运行时需要的包，^19.0.0 表示「允许 19.x 内的更新版本」；
• devDependencies：只在开发时用的工具（构建、测试、类型检查）。

package-lock.json（锁文件）把每个依赖的精确版本和下载地址钉死，npm 安装时优先按锁文件装——这是「同一份代码，所有人装出同一个结果」的保障。所以锁文件必须提交进版本库，也不许手改。

示例拆解

在干净目录复现一次完整流程：

mkdir course-table && cd course-table
npm init -y          # 生成 package.json
npm install react    # 写入 dependencies，生成 node_modules 和锁文件
npm run dev          # 执行 scripts 里定义的命令

• node_modules 是依赖的实际代码，体积大且随时可重建：不提交、不拷贝；换机器只拷代码加锁文件，npm install 一条命令还原。
• 验证复现性：删掉 node_modules 重新 install，对比锁文件——一个字符都不该变。
• 拷贝别人项目时的标准动作：拿到 package.json 和锁文件后 npm install，再 npm run dev；报「找不到脚本」就说明 package.json 没拷全。

动手任务

本课没有在线实验，本机完成：

1. 建一个 modules-demo 目录：写 format.js（命名导出两个函数）和 main.js（导入并调用它们），同目录放一个写了 "type": "module" 的 package.json，用 node main.js 跑通。
2. 把整个目录复制一份，删掉 node_modules 和锁文件，重新 npm install，确认 node main.js 结果一致。
3. 打开本工作台项目（或任意前端项目）的 package.json 回答：dev 和 build 两个脚本分别执行什么？dependencies 里哪个包最大、是干什么的？

常见错误

• 拷项目只拷 src：没有 package.json 和锁文件，别人装不出你的依赖；至少要带上 package.json、锁文件和启动说明。
• 手改锁文件，或装完包不提交锁文件：锁文件与 package.json 对不上时，团队每个人装出的版本都可能不同。
• 依赖装错区：代码运行时 import 的包进 dependencies；构建和测试工具进 devDependencies，装错上线会缺包。
• 相对路径忘了 ./：import { x } from 'format' 会被当成包名去 node_modules 里找；自己的文件要写 './format.js'。

检查与复盘

完成下方检查题确认理解。自查清单：

• 能说清默认导出和命名导出的导入写法差别
• 看到 package.json 能说出 scripts、dependencies、devDependencies 各管什么
• 知道锁文件为什么必须提交，以及「删 node_modules 重装」是排查依赖问题的常规操作

参考资料

• MDN：JavaScript 模块 —— export/import 的系统讲解
• npm 文档：package.json —— 字段含义的官方说明
• npm 文档：package-lock.json —— 锁文件的作用与格式