Bun 自定義注冊(cè)表實(shí)戰(zhàn)快速接入私有包源與排錯(cuò)避坑指南【免費(fèi)下載鏈接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one項(xiàng)目地址: https://gitcode.com/GitHub_Trending/bu/bun上周 CI 構(gòu)建失敗日志停在很具體的一行公網(wǎng)的lodash裝上了私有的acme/ui-kit報(bào) 404。包管理器明明工作正常私有包卻一件都拉不下來(lái)——問(wèn)題出在私有源根本沒(méi)配或者配錯(cuò)了地方。Bun 把「按 scope 路由到不同注冊(cè)表」這件事做成了bunfig.toml里的一小段配置私有包管理的門檻因此低了很多。這篇文章講三件事私有包到底怎么被 Bun 解析、最小可行配置怎么寫、以及離線發(fā)版和 CI 里怎么不出事。私有包是怎么被 Bun 找到的核心機(jī)制一句話按包名前綴路由沒(méi)命中的走默認(rèn)源。帶acme前綴的包去[install.scopes]里配的那條 URL 找沒(méi)有任何規(guī)則命中的包去install.registry指定的默認(rèn)注冊(cè)表找不配就是registry.npmjs.org。配置不是只有一個(gè)入口。Bun 按下面的順序加載后加載的覆蓋先加載的~/.npmrc項(xiàng)目里的.npmrcbunfig.toml全局再到項(xiàng)目環(huán)境變量BUN_CONFIG_REGISTRY/BUN_CONFIG_TOKEN命令行參數(shù)--registry所以老項(xiàng)目的.npmrc不用急著改Bun 直接讀。想統(tǒng)一配置時(shí)官方建議遷移到bunfig.toml。注冊(cè)表這部分配置參考倉(cāng)庫(kù)內(nèi)文檔docs/pm/scopes-registries.mdx.npmrc兼容細(xì)節(jié)在docs/pm/npmrc.mdx。最小可行配置一條 scope 規(guī)則三步搞定改bunfig.toml→ 驗(yàn)證 → 裝包。第 1 步在項(xiàng)目根目錄的bunfig.toml里加一段[install.scopes] acme { url https://npm.acme.dev/, token $NPM_TOKEN }第 2 步先別急著裝預(yù)覽一下解析結(jié)果bun install --dry-run第 3 步像裝公網(wǎng)包一樣裝私有包bun add acme/ui-kit幾個(gè)細(xì)節(jié)值得記住scope作用域就是包名里的acme部分Bun 靠它決定包去哪找。認(rèn)證不用 token 也行用戶名密碼同樣支持acme { url https://npm.acme.dev/, username ci, password $NPM_PASSWORD }token 寫$NPM_TOKEN而不是明文Bun 會(huì)替換環(huán)境變量。bunfig.toml通常要提交進(jìn)倉(cāng)庫(kù)token 永遠(yuǎn)走環(huán)境變量注入。離線發(fā)版緩存 兩個(gè)開關(guān)裝過(guò)的包不會(huì)消失。Bun 把每個(gè)包存進(jìn)全局緩存~/.bun/install/cache按「包名版本」分目錄多個(gè)版本可以共存拷進(jìn)node_modules時(shí)走 Linux/Windows 硬鏈接、macOS 寫時(shí)復(fù)制磁盤上只存一份多個(gè)項(xiàng)目共享。緩存機(jī)制說(shuō)明在倉(cāng)庫(kù)文檔docs/pm/global-cache.mdx。離線場(chǎng)景兩個(gè)開關(guān)級(jí)別不同--prefer-offline緩存優(yōu)先緩存里缺的才聯(lián)網(wǎng)補(bǔ)--offline完全不碰網(wǎng)絡(luò)缺包直接報(bào)錯(cuò)逼你提前備齊。bun install --offline --frozen-lockfile「預(yù)熱好的緩存 --frozen-lockfile--offline」組合可以讓 CI 構(gòu)建完全確定、完全不聯(lián)網(wǎng)——這是內(nèi)網(wǎng)發(fā)版能跑通的底牌。CI 集成把 token 從代碼里挪走CI 里做兩件事用bun ci代替bun install。它等價(jià)于install --frozen-lockfile版本號(hào)鎖定在bun.lock上且package.json與 lockfile 不一致時(shí)直接失敗而不是悄悄幫你改 lockfiletoken 走 CI secrets 注入環(huán)境變量命令前綴即可NPM_TOKEN$NPM_TOKEN bun ci.npmrc寫法同樣支持變量引用//npm.acme.dev/:_authToken${NPM_TOKEN}。 裝完如果懷疑有包帶「偷跑」的安裝腳本Bun 默認(rèn)攔截依賴的生命周期腳本只有列進(jìn)package.json的trustedDependencies才放行。跑一下bun pm untrusted就能看到被攔下的是誰(shuí)確認(rèn)無(wú)誤后用bun pm trust 包名顯式放行。踩過(guò)的坑按錯(cuò)誤反查配置401 Unauthorized先跑bun pm whoami驗(yàn)證當(dāng)前 token 對(duì)哪個(gè)源有效再確認(rèn) scope 指向的 URL 和 token 簽發(fā)的源是同一個(gè)。最常見(jiàn)的原因是 token 換了沒(méi)同步或 scope 配錯(cuò)了源。404 / 包走了錯(cuò)誤的源通常是 scope 拼寫和包名前綴對(duì)不上acme配成ACME這類。用bun install --dry-run看解析預(yù)覽一眼能看出包被路由去了哪。版本像被釘死了懷疑緩存里是舊元數(shù)據(jù)清掉全局緩存重拉bun pm cache rm本地和 CI 結(jié)果對(duì)不上先確認(rèn)bun.lock提交了、兩邊都用bun ci再用bun why 包名打印依賴鏈看它到底是哪條路徑拉進(jìn)來(lái)的。什么時(shí)候配、配多少你的場(chǎng)景需要做的純公網(wǎng)依賴什么都不用配一個(gè)組織一批私有包[install.scopes]里一條規(guī)則完事多個(gè)私有源混用默認(rèn)install.registry兜底 每條 scope 精確匹配內(nèi)網(wǎng)發(fā)版 / 離線環(huán)境預(yù)熱緩存 --offline --frozen-lockfile已在用 npm / yarn.npmrc原樣保留就能跑之后逐步遷到bunfig.toml最后給一句選型建議配置越少越容易維護(hù)。能一條 scope 規(guī)則解決的就別去動(dòng)默認(rèn)注冊(cè)表能復(fù)用.npmrc的就先跑起來(lái)再遷移。Bun 這套注冊(cè)表機(jī)制的邊界很清晰——路由、認(rèn)證、緩存三件事各管一段把這三段想明白私有包管理基本不會(huì)再給你挖坑?！久赓M(fèi)下載鏈接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one項(xiàng)目地址: https://gitcode.com/GitHub_Trending/bu/bun創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考