想象一下，你是一位大厨，为了让旗下连锁餐厅都能做出同样美味的料理，你研发了一系列“秘密酱汁”。你希望这些酱汁能被分送到各个分店，但又不能让外面的路人随便拿走。
在软件开发的世界里，这些秘密酱汁就是公司内部的“私有包”。
当项目多起来后，你一定遇过这种困扰：同一个 UI 组件或工具函数，难道要在每个项目里复制粘贴吗？或者用 Git Submodule 管理到怀疑人生？其实，你只需要建立一个“私有食材库（Private NPM Registry）”。今天我们就来聊聊，如何使用 pnpm 将包发布到 GitLab，让团队成员能像安装开源包一样，简单一行指令搞定。
为什么需要私有包与 Scope？
在 Node.js 的宇宙里，私有包必须有一个“姓氏”，这就是 Scope（作用域）。
比如说，你们公司名字叫 @my-company，那包名字可能就长这样：@my-company/ui-kit。有了这个姓氏，当 pnpm 看到它时，就不会傻傻跑到公开的 npmjs.org 乱找，而是直接冲去你指定的公司导航坐标。
关键决策：Group Level vs. Project Level
在 GitLab 里，这就像是你把调味料放哪：
| 层级 | 说明 |
|---|---|
| Project Level (项目层级) | 像是主厨的私人保险箱，只有特定菜色的人能用。设置起来比较繁琐，每个包都要独立设置。 |
| Group Level (群组层級) | 这就是“中央厨房”的概念，强烈推荐！只要设置一次，同个群组下的一打甚至几百个包，都能共用同一套设置与凭证。 |
设置“通行证”：Access Token 与环境变量
要进入地下粮仓，你得先领一张“门禁卡”。
- 到 GitLab 的 Settings > Access Tokens。
- 申请一个 Token，权限勾选
read_api(下载用) 与write_package_registry(发布用)。 - 重要： 领到 Token 后，绝对不要直接写死在代码或
.npmrc文件里！这就像把金库钥匙插在门上。
最专业做法是把它藏在“环境变量”里。在你的 Mac 或 Linux 终端（如 ~/.zshrc）加入这行：
export GITLAB_TOKEN="你的_GitLab_Token"
这样系统就会自动帮带上凭证，安全又方便。
导航设置：.npmrc 的奥义
接着，我们要在项目根目录建立一张导航地图 .npmrc，告诉 pnpm 怎么走：
# 看到 @my-company 开头的，请去 GitLab 找
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/
# 设置门禁卡认证（读取我们刚刚设好的环境变量）
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"
只要换上你们公司的 Group ID，这条路就铺好了！
发布前的最后一步：包装的艺术
很多人设置完连通就急着发布，结果一不小心就把测试文件、甚至是秘密设置也一起传上去了。这时 package.json 的 files 字段 就派上用场了。
这是一个“白名单”的概念：
{
"name": "@my-company/lib-1",
"files": [
"dist"
],
"publishConfig": {
"registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
}
}
| 设置 | 说明 |
|---|---|
files |
明确告诉系统，我只要发布 dist 内的编译精华，其他垃圾都留在原地。 |
publishConfig |
这是双重保险，确保这个包绝对不会手滑发布到公海（npmjs.org）。 |
发布前，建议用 pnpm pack 指令在本地先开箱检查一下，确认 package 内容没问题后，再潇洒地打下 pnpm publish！
总结
建立私有食材库并不难，关键在于：
- 申请 Token 并妥善用环境变量保护。
- 配置正确的
.npmrc导航地图。 - 利用
package.json的files字段做到精准出货。
学会这套流程，你也能让公司的代码重用变得专业、安全且优雅。现在就去动手打造你们的中央厨房吧！