离线环境打包 JavaScript 模块的核心难点是构建工具无法联网解析裸导入（如 import _ from 'lodash'），必须提前在联网环境完整安装 node_modules、锁定依赖版本，并禁用所有网络行为（如 Vite 的 optimizeDeps、Webpack 的远程 fallback），同时通过 alias 或 external 显式处理模块路径，确保产物完全自包含且离线可运行。
离线环境打包 JavaScript 模块，核心难点不是“写不写 import”，而是让构建工具在没有网络时仍能准确找到、解析并包含所有外部依赖（比如 lodash、vue、axios 等）。浏览器原生不支持包名导入，Node.js 的模块解析机制也依赖 node_modules 和 package.json，而这些在离线时若未提前准备，就会直接失败。
确保 node_modules 完整且已预装
离线打包的第一前提是：整个项目的 node_modules 文件夹必须已在联网环境下完整安装好，包括所有间接依赖（即依赖的依赖）。仅拷贝部分包或手动放几个 .js 文件是不可靠的。
- 推荐用
npm ci --no-audit --no-fund或yarn install --frozen-lockfile在联网机器上安装，保证 lock 文件与 node_modules 严格一致 - 检查
node_modules/xxx/package.json中是否有"exports"、"module"、"main"字段，避免某些包因字段缺失导致解析失败 - 特别注意带二进制或需编译的包（如 bcrypt、canvas），它们在离线时无法重新构建，必须提前完成编译并保留
node_modules/xxx/build/等产物
禁用动态包解析和远程请求
很多构建工具默认会尝试访问 registry 或 CDN（比如 Vite 的依赖预构建、Webpack 的 resolve.fallback 对 node 内置模块的 polyfill 注入），这些行为在离线时会卡住或报错。
- Vite：在
vite.config.js中显式关闭预构建，并锁定解析路径：build: { rollupOptions: { external: ['lodash'] } }（慎用 external）
更稳妥的是设optimizeDeps: { disabled: true }，并确认所有 import 路径都是相对或绝对本地路径（不写'lodash'，改用'lodash-es'并确保它已存在于 node_modules 中） - Webpack：移除或注释掉所有含
https://或cdn.的 plugin 配置；resolve.modules只留['node_modules']，不加空字符串或全局路径
使用本地 alias 替代裸导入（bare imports）
浏览器和打包器都不认识 import _ from 'lodash' 这种写法——它依赖 Node.js 的模块解析算法。离线时更不能指望自动查找，应改为显式指向本地文件。
立即学习“Java免费学习笔记（深入）”；
- 在 Webpack 中配置：
resolve: { alias: { lodash: path.resolve(__dirname, 'node_modules/lodash-es/index.js') } } - 在 Vite 中配置：
resolve: { alias: { lodash: 'lodash-es' } }（前提是 lodash-es 已安装且为 ESM 格式） - 对非 ESM 包（如旧版 lodash），可用
rollup-plugin-commonjs或@rollup/plugin-commonjs处理，但必须确保插件本身及所需依赖也已离线安装
验证打包产物是否真正自包含
执行打包命令后，不要只看 dist 目录有没有生成文件，要确认它是否真的不依赖外部资源：
- 打开生成的
dist/index.html，用浏览器离线打开（断网 + 关闭开发者工具 Network 面板的 “Disable cache”），看是否白屏或报 404 - 检查 dist/assets/*.js 里是否还存在
require('')、__webpack_require__调用未被替换，或仍有import('./chunk-xxx.js')加载远程路径 - 用
grep -r "node_modules\|https://" dist/快速扫描残留的外部引用痕迹
离线打包不是功能开关，而是工程准备状态。只要 node_modules 是全量、锁文件是确定、配置不触发任何网络行为，Vite build 或 webpack --mode production 就能稳定输出可离线运行的产物。
