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