1. 先把问题拆清楚：tgz 包里的资源到底怎么被“看到”
你遇到的这个场景，我太熟悉了。项目里把某个公共能力模块（就叫它 Hsp 吧，你可以理解为一组模板、静态资源、JS 逻辑打包在一起的复合模块）单独编译成一个 tgz 包，然后交给其他模块去用。表面上看这是个“打包 + 引用”的简单问题，但实际落地时，你会发现整条链路里有四五个隐藏关卡：路径解析、包内容白名单、exports 子路径限制、node_modules 安装方式、甚至还有缓存。
先说清楚 tgz 到底是什么形态。在 Node/npm 生态里，npm pack会把一个模块压缩成.tgz，本质上是 tar.gz 格式的归档文件，里面包含该模块的 package.json、代码、模板、样式、图片等所有被纳入打包范围的文件。其他模块引用它时，通常有三种路径：一是通过 package.json 里的dependencies字段指向 tgz 文件路径，安装后它会解压到node_modules/hsp/目录里，走正常的 Node 模块解析；二是在构建脚本里直接解压 tgz 提取资源；三是在打包器配置里做路径别名映射。
最容易被坑的点，其实是资源引用链路的“最后一公里”。很多人以为把 tgz 装进 node_modules 就完事了，结果一跑起来，模板读不到、图片 404、样式引入失败。问题往往不是 tgz 打包本身出错，而是“包里的文件路径”和“引用方的解析方式”之间没对齐。所以这篇文章我会先把打包前的目录规划讲透，再给四种经过实测的引用方式，最后附上排查手册。适合前端工程化负责人、Node 服务端开发，以及所有正在被“模块打包 + 资源复用”折磨的同学。
2. 打包前必须做对的目录规划与清单声明
2.1 package.json 的 files 字段决定 tgz 里到底有什么
先记住一个原则：tgz 包里有什么，不是看项目目录里有什么，而是看 package.json 的files字段怎么说。如果你的 Hsp 模块目录里有assets/、templates/、src/、dist/，但files里只写了["dist"]，那打出来的 tgz 就只有 dist 目录，资源自然全丢。
我常用的声明方式是显式列出所有要对外发布的路径：
{ "name": "hsp", "version": "1.0.0", "main": "dist/index.js", "files": [ "dist", "assets", "templates", "README.md" ] }这里有个细节：files字段支持目录级白名单，它会保留目录内部的相对结构。比如assets目录下有images/logo.png、css/base.css，安装后访问路径就是node_modules/hsp/assets/images/logo.png。相比.npmignore黑名单机制，files白名单更可控——黑名单容易漏，白名单顶多多写几个路径，不会把不该带的私密配置打进去。
2.2 静态资源与模板资源的统一出口设计
资源能不能被稳定引用，还取决于你给它们设计了一个什么样的“出口”。我踩过几次坑之后，总结出的推荐结构是：
hsp/ ├── dist/ # 编译后的 JS 产物 ├── assets/ # 图片、字体、CSS 等静态资源 │ ├── images/ │ └── css/ ├── templates/ # hbs/ejs 等模板文件 │ ├── layout/ │ └── partials/ ├── package.json └── README.md统一出口的意思是：不要让资源散落在src/config/../../xxx这种深层路径里，而是固定放在assets和templates两个顶层目录下。这样无论是引用方写相对路径、用require.resolve定位、还是做打包器 alias，都只需要记两个前缀，心智负担小很多。
还有一个容易踩的坑是exports字段。如果你在 package.json 里写了exports，它会变成“门禁”：默认情况下，引用方只能访问 exports 里显式声明的子路径，hsp/templates/xxx.hbs这种访问会被 Node 直接拒绝。规范做法是给资源目录单独开子路径映射：
{ "exports": { ".": "./dist/index.js", "./templates/*": "./templates/*", "./assets/*": "./assets/*" } }这样既保住了入口的封闭性，又给资源留了通道。我见过不少项目就是因为只写了"."，导致外部模块引用模板时报ERR_PACKAGE_PATH_NOT_EXPORTED。
3. 编译生成 tgz 包的完整操作
3.1 用 npm pack 生成标准 npm 包格式的 tgz
npm pack是主线方案，因为它生成的 tgz 和 npm registry 上的包格式完全一致，后续安装时 npm/yarn/pnpm 都能正确识别，lockfile 也会自动记录 tgz 的 integrity 哈希。
操作流程分三步。第一步，先编译产物，确保dist/目录里的 JS 是最终可运行的版本：
npm run build第二步，预览打包内容，这一步非常重要，别跳过。--dry-run会列出所有将被写进 tgz 的文件，方便你确认 assets、templates 是否都在：
npm pack --dry-run第三步，正式打包，指定输出目录避免 tgz 散落在项目根目录：
npm pack --pack-destination ../artifacts执行完会在../artifacts下生成类似hsp-1.0.0.tgz的文件。文件名规则固定是包名-版本号.tgz，这个规则后面引用时会用到。
3.2 用 tar 命令手动打包的适用场景
有些团队不用 npm pack，而是用tar命令直接打，常见于需要把 dist 和外部资源临时拼装在一起，或者要控制包内部顶层目录结构的场景。比如你想让 tgz 解压后直接是一个hsp/目录，可以这样：
tar -czf hsp-bundle.tgz -C ../build_output hsp这里-C指定进入目录，hsp是那里面的一层目录，解压后会得到hsp/包裹结构。如果你是给构建系统用，不一定要包一层目录，可以直接把内容压到根上：
tar -czf hsp-assets.tgz -C dist .手动打包的优点是结构完全可控，缺点是 npm 不会把它当标准依赖包处理，引用方的 lockfile 里也不会带 integrity。我建议优先用 npm pack，只有在你明确只需要“纯资源包”而不是“可执行模块包”时才走手动 tar。
3.3 打包脚本的自动化配置
手动敲命令容易漏步骤，我习惯在 Hsp 模块的 package.json 里固化一条打包脚本：
{ "scripts": { "build": "tsc -p tsconfig.build.json && npm run copy:assets", "copy:assets": "cpr assets dist/assets -o", "pack:tgz": "npm run build && npm pack --pack-destination ../artifacts" } }注意copy:assets这一步：如果想把 assets 也作为 JS 入口的相邻资源一起发布，可以在构建时把静态资源复制进 dist；如果你更希望 assets 作为独立顶层目录保留，那就不复制，而是靠files字段里的"assets"声明带进去。两种策略各有适用场景——复制进 dist 适合交给 CDN 或打包器托管，保留独立目录适合通过 express.static 直接暴露。
我个人的习惯是二者都保留：模板走独立templates/目录，图片字体等二进制走assets/，这样引用方选择余地最大。
4. 其他模块引用 tgz 资源的四种典型方式
4.1 方式一：作为 npm 依赖安装后按包路径引用
这是最主流、最省心的方式。在引用方的 package.json 里，把 tgz 直接写进 dependencies：
{ "dependencies": { "hsp": "file:../artifacts/hsp-1.0.0.tgz" } }然后执行npm install。npm 会把 tgz 解压安装到node_modules/hsp/，并且 lockfile 里会记录来源：
"hsp": { "version": "1.0.0", "resolved": "file:../artifacts/hsp-1.0.0.tgz", "integrity": "sha512-..." }引用的时候，JS 逻辑走require('hsp')或import ... from 'hsp'。资源引用我用的是这套组合拳，实测很稳：
const path = require('path'); const { createRequire } = require('module'); const requireFromHsp = createRequire(require.resolve('hsp/package.json')); // 定位模板文件的真实路径 const headerTemplate = requireFromHsp.resolve('../templates/layout/header.hbs'); console.log('模板路径:', headerTemplate); // 在 Node 服务里读取模板内容 const fs = require('fs'); const content = fs.readFileSync(headerTemplate, 'utf-8');这里有两个关键点。第一，用createRequire(require.resolve('hsp/package.json'))拿到的是 Hsp 包内部视角的路径解析器，能自动处理exports映射、pnpm 软链、yarn workspace 提升等复杂情况，比path.join(process.cwd(), 'node_modules/hsp/xxx')这种硬拼路径靠谱得多。第二，hsp/package.json这个子路径能在大多数 exports 配置下被解析到，因为它属于 Node 对package.json的特殊放行规则。
4.2 方式二：构建期直接解压复用资源
如果你的 tgz 只是用来传递静态资源，比如一组设计规范图片、一套多语言 JSON、一批字体文件，并不需要安装成 node_modules 里的包，那可以在构建脚本里直接解压。
我用 Node 脚本配合tar包来解，流程可控、跨平台：
const fs = require('fs'); const path = require('path'); const { execSync } = require('child_process'); const tarball = path.resolve(__dirname, '../artifacts/hsp-1.0.0.tgz'); const dest = path.resolve(__dirname, '../public/vendor/hsp'); fs.mkdirSync(dest, { recursive: true }); // 解压后顶层是 package/，因为 npm pack 会包一层目录 execSync(`tar -xzf "${tarball}" -C "${dest}" --strip-components=1`); console.log('Hsp 资源已解压至:', dest);--strip-components=1是为了去掉 npm pack 生成的顶层package/目录，让 assets、templates 直接落在public/vendor/hsp/下。这样引用方的前端代码可以直接通过/vendor/hsp/assets/css/base.css访问，不需要经过 Node 模块解析，也没有 exports 限制，特别适合纯静态托管场景。
这个方式的优点是解耦：tgz 只是产物交付物，和 npm 运行时依赖完全无关。缺点是少了版本依赖管理，你得自己在构建脚本里做版本比对，防止用了旧 tgz。
4.3 方式三：在打包器配置里把资源映射到别名
如果你用的是 Webpack 或 Vite，而且希望直接在源码里importtgz 包内的资源，那就在打包器配置里做 alias 别名。
Webpack 的resolve.alias配置：
// webpack.config.js const path = require('path'); module.exports = { resolve: { alias: { 'hsp-assets': path.resolve(__dirname, 'node_modules/hsp/assets'), 'hsp-templates': path.resolve(__dirname, 'node_modules/hsp/templates') } } };Vite 的配置类似：
// vite.config.js import path from 'path'; import { defineConfig } from 'vite'; export default defineConfig({ resolve: { alias: { 'hsp-assets': path.resolve(__dirname, 'node_modules/hsp/assets'), 'hsp-templates': path.resolve(__dirname, 'node_modules/hsp/templates') } } });配置完之后，引用方代码里可以直接这样写：
import 'hsp-assets/css/base.css'; import logoUrl from 'hsp-assets/images/logo.png';这里注意，alias 的路径是硬编码依赖node_modules/hsp存在。如果用 pnpm 管理依赖，node_modules 下的 hsp 可能是一个指向.pnpm/hsp@1.0.0/node_modules/hsp的软链，alias 仍然能正常工作，因为path.resolve最终指向的软链接路径在文件系统层面是可访问的。但如果你的项目开启了 pnpm 的symlink=false之类配置，建议改用第一节的createRequire方案，避免硬路径失效。
4.4 方式四：通过服务端静态路由暴露资源目录
如果你在跑 Node 服务，还要把 Hsp 包里的资源开放给浏览器直接请求，那就在服务端挂一个静态路由。我用 Express 演示：
const express = require('express'); const path = require('path'); const { createRequire } = require('module'); const app = express(); // 拿到 Hsp 包的实际安装目录 const req = createRequire(require.resolve('hsp/package.json')); const hspRoot = path.dirname(req.resolve('package.json')); // 把 assets 和 templates 作为静态目录暴露 app.use('/hsp/assets', express.static(path.join(hspRoot, 'assets'))); app.use('/hsp/templates', express.static(path.join(hspRoot, 'templates'))); app.listen(3000);这样浏览器可以直接访问http://localhost:3000/hsp/assets/images/logo.png。关键还是用createRequire定位包的真实目录，而不是path.join(process.cwd(), 'node_modules/hsp')。后者在 monorepo 或者 pnpm 环境下经常指向错误位置，因为工作目录可能不是引用方所在的包目录。
5. 引用过程中的常见故障与排查手册
我在实际项目里帮别人排查过不少类似问题，整理成一张速查表，覆盖率和命中率都比较高。
| 现象 | 根因 | 处理方式 |
|---|---|---|
ERR_PACKAGE_PATH_NOT_EXPORTED | package.json 的exports字段限制了子路径 | 在 Hsp 包里给templates/*、assets/*加显式映射 |
| 引用的文件提示找不到 | files白名单没包含资源目录 | 用npm pack --dry-run检查，补充files声明 |
模板路径变成undefined | require.resolve用错了解析器 | 改用createRequire(require.resolve('hsp/package.json')) |
| 修改 tgz 后引用方仍在用旧内容 | npm 的 file 依赖缓存了旧的 tgz | 删掉node_modules和 lockfile 里对应条目后重新 install |
| pnpm 下资源访问失败 | 包被软链到了.pnpm目录，硬编码路径失效 | 用createRequire解析，或在.npmrc里配置public-hoist-pattern |
| Windows 上路径拼接出错 | /和\混用 | 统一用path.join或upath处理跨平台路径 |
| tgz 内没有预期文件 | 打包前未跑构建，或构建产物被清理 | 检查dist/是否存在，打包脚本先执行 build |
5.1 资源 404 或路径错位的排查流程
每次遇到资源 404，我都是按这个顺序排查。第一步，确认 tgz 里到底有没有这个文件，直接看包内容：
tar -tzf ../artifacts/hsp-1.0.0.tgz | grep assets没有就去回看files白名单和npm pack --dry-run输出。第二步，确认文件被装到了哪，看引用方的 node_modules：
ls node_modules/hsp/assets第三步，确认引用代码里的路径是否和实际文件结构对齐。很多 404 不是包的问题，而是引用方多写了一层目录，或者少写了一个子目录层级。
5.2 tgz 内部文件缺失的排查流程
文件缺失通常是两种原因：构建产物不完整，或者打包白名单漏了路径。我建议在 Hsp 模块的 CI 或者本地脚本里加一个“内容校验”步骤，打包后立刻检查关键文件是否存在：
const fs = require('fs'); const { execSync } = require('child_process'); const list = execSync(`tar -tzf ../artifacts/hsp-1.0.0.tgz`, { encoding: 'utf-8' }); const required = [ 'package/package.json', 'package/dist/index.js', 'package/assets/css/base.css', 'package/templates/layout/header.hbs' ]; const missing = required.filter((file) => !list.includes(file)); if (missing.length) { throw new Error(`tgz 缺少关键文件: ${missing.join(', ')}`); } console.log('tgz 内容校验通过');把它接进npm pack之后的流程，能在打包阶段就拦住大部分资源缺失问题，而不是等到引用方跑起来才发现。
5.3 缓存导致的过期引用
这一条尤其坑。npm 对file:依赖的处理策略是看 tgz 文件的 mtime 和内容。如果你重新生成了同名同版本的 tgz，npm 有时不会重新拷贝，导致引用方拿到的是旧包。我用的规避方式是：每次发布都升版本号，让 tgz 文件名变化；或者把 tgz 路径里的版本改成带构建号：
npm pack --pack-destination ../artifacts mv ../artifacts/hsp-1.0.0.tgz ../artifacts/hsp-1.0.0-$(date +%Y%m%d%H%M).tgz引用方 package.json 指向的路径同步更新为带时间戳的文件名。虽然麻烦，但从根上避开了同版本覆盖导致的缓存混淆。如果不想改名，那就提醒团队每次更新后先删引用方node_modules/hsp再 install：
rm -rf node_modules/hsp npm install6. 还有一些实操层面的经验
最后分享几个我在多轮项目迭代里沉淀下来的习惯，不一定写在哪篇文档里，但能省不少事。
第一，Hsp 包里如果有模板资源，尽量不要在模板内部用绝对路径引用图片或 CSS，比如/assets/images/logo.png这种。因为发布成 tgz 后，它的“根目录”概念会被安装方改变，绝对路径会直接飘走。模板里应该用相对路径，或者由引用方在渲染模板时注入资源前缀。这也是我们团队从模板 404 踩坑里总结出来的硬性规定。
第二，如果团队用 monorepo，而且项目之间本来就频繁依赖，那长期来看更推荐把 Hsp 发布到私有镜像源，而不是到处分发 tgz 文件。tgz 适合离线交付、跨网络传递、或者不想搭私有源的场景，但它有几个天然劣势：没有版本区间语义，不能统一在源上做权限管理，升级时还要手动替换文件路径。我一般把 tgz 当作“增量交付产物”看待，而不是替代私有源的方案。
第三，引用方写死的node_modules/hsp路径能不用就不用。哪怕你现在是简单的 npm 扁平目录结构，也不能保证未来迁移 pnpm 或者 yarn PnP 后还能通。把路径解析统一收敛到createRequire或者打包器 alias，未来迁移的成本会低非常多。这个经验是我们从 npm 迁移 pnpm 时付出的换来的，当时项目里三处硬编码路径全部失效，几乎是重写了一份资源定位模块。
总之，Hsp 模块打 tgz、其他模块引资源，核心就是把“包里有什么、装到哪里去、用什么方式定位”这三件事分开想清楚。目录规划、files 白名单、exports 子路径、路径解析方式，每一个环节都遵循“显式声明、规范出口、工具解析”的思路，基本上就不会出大问题。如果你正在被某个引用问题卡住，先回去看一眼 tgz 的实际文件列表和引用方的解析方式，80% 的根因都藏在这两个地方。
