如何通过npm在HTML项目中高效管理前端依赖包？

本文共计1088个文字，预计阅读时间需要5分钟。

HTML 本身不能直接使用，需要通过以下方式实现：

为什么直接 <script src="node_modules/xxx/index.js"></script> 会失败

常见错误现象：

• 控制台报错 Uncaught ReferenceError: require is not defined
• 引入后变量未挂载到 window，调用时 xxx is not defined
• 依赖嵌套报错，比如某包内部又 require('fs') 或 require('path')，这些 Node 内置模块在浏览器里根本不存在

根本原因：npm 包默认按 CommonJS（CJS）或 ESM 编写，面向 Node.js 运行时；浏览器原生只支持全局变量、UMD 构建版或现代 ESM（且路径必须是相对/绝对 URL，不能是包名）。

所以你看到的 <script src="https://cdn.jsdelivr.net/npm/lodash@4.17.21/lodash.min.js"></script> 能用，是因为 CDN 提供的是已打包好的 UMD 版本，不是原始 npm 包文件。

立即学习“前端免费学习笔记（深入）”；

browserify 是最轻量的“npm → 浏览器”桥梁

适合小项目、快速验证、不想配 webpack 的场景。它把 require() 语句静态分析 + 递归打包，生成一个含所有依赖的 bundle.js。

实操建议：

• 先全局安装：npm install -g browserify
• 新建 src/main.js，写 var _ = require('lodash'); console.log(_.now());
• 确保已 npm install lodash --save（装进 node_modules）
• 执行打包：browserify src/main.js -o dist/bundle.js
• HTML 中直接引入：<script src="dist/bundle.js"></script>

注意：browserify 默认不模拟 Node 内置模块。如果包用了 require('fs')，会报错；此时需手动排除或换包。可用 --ignore fs 或配合 browserify-shim 处理。

webpack 更通用，但配置门槛略高

当你需要代码分割、热更新、CSS/图片处理、TypeScript 支持，或项目已有 Vue/React，就该选 webpack。

关键差异点：

• entry 必须是文件路径（如 ./src/index.js），不能是包名
• 默认启用模块解析，能自动处理 require('lodash') 和 import _ from 'lodash'
• 需额外装 html-webpack-plugin 才能自动生成 index.html 并注入 <script>
• 生产模式（--mode=production）自动压缩、Tree Shaking，但可能剔除未显式引用的导出（比如只用了 _.debounce，却没 import 整个 lodash）

最小可行配置示例（webpack.config.js）：

const HtmlWebpackPlugin = require('html-webpack-plugin'); module.exports = { entry: './src/index.js', plugins: [new HtmlWebpackPlugin({ template: './src/index.html' })], mode: 'development' };

然后运行 npx webpack，输出自动放进 dist/，含 HTML + JS。

别忽略 package.json 的 role 和 scope

很多人以为 package.json 只是记录依赖，其实它直接影响构建行为：

• "type": "module" 在根目录会强制所有 .js 文件按 ESM 解析，require() 报错；browserify 不支持 ESM，webpack 需设 experiments.topLevelAwait: true
• dependencies vs devDependencies：browserify / webpack 打包时默认都读取，但部署时若删掉 node_modules，只有 dependencies 会被 npm install 恢复——所以工具类包（如 webpack）务必放 devDependencies
• exports 字段（Node.js 12.20+）会影响模块解析优先级，某些包（如 lodash-es）只暴露 ESM 入口，CJS 工具链可能无法识别

最容易被忽略的一点：browser 字段。有些包（如 ws）在 package.json 里声明了 "browser": {"net": false, "tls": false}，这是告诉打包工具「浏览器环境跳过这些 Node 专属模块」——browserify 和 webpack 都会尊重它，但裸写 require('ws') 仍可能因未处理 fallback 而失败。