Bunのbun.lockとnpmのpackage-lock.jsonの違い
bun.lock と package-lock.json は、どちらも入れたパッケージのバージョンと integrity(中身のハッシュ)を記録するファイルです。記録の中身はほぼ同じですが、書き方と、互いのファイルを読むかどうかが違います。Bun は package-lock.json を読めますが、npm は bun.lock を読まず、package.json から入れ直します。
npm から Bun に乗り換えるときや、CI で依存のバージョンを固定したいときに、ロックファイルをどう扱えばよいかをまとめました。私は検証環境で、同じ package.json から2つのファイルを作り、中身と動きを比べました。
検証環境は Ubuntu 24.04(x86_64)、Node.js 22.23.4(npm 10.9.9)、Bun 1.4.4 です。パッケージは registry.npmjs.org から取得しました。workspaces を使うプロジェクト、git: や file: の依存、古い形式の bun.lockb、Windows と macOS は試していません。Bun と npm の公式ドキュメントは、検証に使った版(Bun はタグ bun-v1.4.4、npm はタグ v10.9.9)の元ファイルを GitHub で確認しています。
同じ package.json から作った2つのファイル
依存が2つだけの package.json を、npm 用と Bun 用の2つのフォルダに置きました。
{
"name": "lock-demo",
"version": "1.0.0",
"private": true,
"dependencies": {
"debug": "^4.3.7",
"chalk": "^5.3.0"
}
}
それぞれのフォルダで npm install と bun install を実行しました。どちらも chalk 5.6.2、debug 4.4.3、debug が依存している ms 2.1.3 の3つを入れています。できたロックファイルの大きさは次のとおりです。
$ wc -c -l n/package-lock.json b/bun.lock
51 1457 n/package-lock.json
20 751 b/bun.lock
package-lock.json は 51 行、1,457 バイトで、bun.lock は 20 行、751 バイトでした。bun.lock の全体は次のとおりです。
{
"lockfileVersion": 2,
"configVersion": 1,
"workspaces": {
"": {
"name": "lock-demo",
"dependencies": {
"chalk": "^5.3.0",
"debug": "^4.3.7",
},
},
},
"packages": {
"chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
"debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" }, "peerDependencies": { "supports-color": "*" }, "optionalPeers": ["supports-color"] }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
"ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
}
}
1つのパッケージの書き方の違い
同じ ms 2.1.3 を、package-lock.json は次のように書いていました。
"node_modules/ms": {
"version": "2.1.3",
"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
"integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
"license": "MIT"
}
bun.lock では、1つのパッケージが1行の配列になっています。
"ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
比べると、違いは次の3つでした。
| 項目 | package-lock.json | bun.lock |
|---|---|---|
| キー | node_modules/ms(入れる場所) |
ms(パッケージの名前) |
| ダウンロード元の URL | resolved に tarball の URL を書く |
2番目の要素が空の文字列で、URL は書いていない |
| ライセンスや対応する Node.js のバージョン | license を書く(chalk と debug では engines も) |
書いていない |
integrity の値は、3つのパッケージとも2つのファイルでまったく同じでした。キーの違いについては、package-lock.json の公式ドキュメントにも、packages の各項目のキーは、プロジェクトのフォルダからの相対パスにすると書かれています。
もう1つの違いは、bun.lock は最後の要素のあとにもカンマを付けることです。そのため、Node.js の JSON.parse では読めません。
$ node -e 'JSON.parse(require("fs").readFileSync("b/bun.lock","utf8")); console.log("ok")'
(中略)
SyntaxError: Expected double-quoted property name in JSON at position 187 (line 10 column 7)
(以下、スタックトレースが続くので省略)
package-lock.json は同じコマンドで読めました。Bun 用のフォルダで Bun を使うと、require("./bun.lock") で読み込めて、lockfileVersion と packages のキーを取り出せました。
$ bun -e 'const l = require("./bun.lock"); console.log(l.lockfileVersion, Object.keys(l.packages))'
2 [ "chalk", "debug", "ms" ]
依存を1つ足したときの差分
どちらのフォルダも git で一度コミットしてから、npm install picocolors と bun add picocolors で picocolors 1.1.1 を足しました。git diff --stat の結果は、npm のフォルダでは次のとおりです。
$ git diff --stat
package-lock.json | 9 ++++++++-
package.json | 3 ++-
2 files changed, 10 insertions(+), 2 deletions(-)
Bun のフォルダでは次のとおりです。
$ git diff --stat
bun.lock | 3 +++
package.json | 3 ++-
2 files changed, 5 insertions(+), 1 deletion(-)
ロックファイルの変更は、package-lock.json が8行の追加と1行の削除、bun.lock が3行の追加だけでした。bun.lock の差分は次のとおりです(ハッシュは途中を省略しています)。
"dependencies": {
"chalk": "^5.3.0",
"debug": "^4.3.7",
+ "picocolors": "^1.1.1",
},
(中略)
"ms": ["ms@2.1.3", "", {}, "sha512-6Flz…"],
+
+ "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH…"],
package-lock.json の1行の削除は、"debug": "^4.3.7" の行です。後ろに picocolors の行が加わったため、カンマを付けた行に書き換わっていました。bun.lock は最後の行にもカンマがあるので、元の行は変わらず、足した行だけが差分に出ています。
package.json とロックファイルが食い違ったとき
CI では、ロックファイルどおりに入れ、package.json と合わなければ止める使い方をします。npm では npm ci、Bun では bun ci です。bun install の公式ドキュメントによると、bun ci は bun install --frozen-lockfile と同じ動きです。
package.json の dependencies に "is-number": "^7.0.0" を手で書き足し、ロックファイルは更新しないまま実行しました。
$ npm ci --no-audit --no-fund
npm error code EUSAGE
npm error
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.
npm error
npm error Missing: is-number@7.0.0 from lock file
(使い方の説明が続くので省略)
$ bun ci
bun install v1.4.4 (38afee6c8)
error: lockfile had changes, but lockfile is frozen
note: dependencies in package.json changed since bun.lock was saved: is-number was added
note: try re-running without --frozen-lockfile and commit the updated lockfile
どちらも終了コード 1 で止まり、ロックファイルは書き換えませんでした(git status で変わっていたのは package.json だけです)。bun install --frozen-lockfile でも、bun ci と同じメッセージが出ました。
次に、依存を足すのではなく、debug の範囲を ^4.3.7 から >=4.3.7 に変えただけで試しました。ロックファイルにある debug 4.4.3 は、どちらの範囲にも入ります。このときは、npm ci も bun ci も止まらずに入れ終わりました。
$ bun ci
bun install v1.4.4 (38afee6c8)
Checked 4 installs across 5 packages (no changes) [1.00ms]
Bun の同じ公式ドキュメントにも、入るバージョンが変わらない書き換え(^1.0.0 を >=1.0.0 にするなど)では止まらないと書かれています。
npm は bun.lock を読まない
bun.lock で chalk を 5.3.0 に固めたフォルダを作り、npm と Bun で入れ比べました。package.json の範囲は ^5.3.0 で、レジストリにはこの範囲に入る 5.6.2 があります。
$ grep -A3 '"packages"' bun.lock
"packages": {
"chalk": ["chalk@5.3.0", "", {}, "sha512-dLitG79d+GV1Nb/VYcCDFivJeK1hiukt9QjRNVOsUtTy1rR1YJsmpGGTZ3qJos+uw7WmWF4wUwBd9jxjocFC2w=="],
}
}
このフォルダを2つに写し、node_modules を消してから、それぞれ npm install と bun ci を実行しました。入った chalk のバージョンは次のとおりです。
$ npm install --no-audit --no-fund && node -p 'require("./node_modules/chalk/package.json").version'
added 1 package in 256ms
5.6.2
$ bun ci && node -p 'require("./node_modules/chalk/package.json").version'
bun install v1.4.4 (38afee6c8)
+ chalk@5.3.0
1 package installed [1.00ms]
5.3.0
npm は bun.lock を使わずに package.json の範囲から選び直し、5.6.2 を入れました。フォルダには新しく package-lock.json ができ、bun.lock もフォルダに残っていました。bun.lock だけがあるフォルダで npm ci を実行すると、package-lock.json がないというエラーで止まりました。
$ npm ci --no-audit --no-fund
npm error code EUSAGE
npm error
npm error The `npm ci` command can only install with an existing package-lock.json or
npm error npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or
npm error later to generate a package-lock.json file, then try again.
(使い方の説明が続くので省略)
bun.lock だけをコミットしたプロジェクトで、誰かが npm install を実行すると、ロックファイルで固めたものとは違うバージョンが入ることがあります。プロジェクトで使うパッケージマネージャーを、npm か Bun のどちらかにそろえておく必要があります。
Bun は package-lock.json を読む
逆に、package.json と package-lock.json だけがあるフォルダで bun ci を実行すると、Bun は package-lock.json を読み込んで入れました。
$ bun ci
bun install v1.4.4 (38afee6c8)
[0.32ms] migrated lockfile from package-lock.json
+ chalk@5.6.2
+ debug@4.4.3
+ picocolors@1.1.1
4 packages installed [2.00ms]
ロックファイルについての Bun の公式ドキュメントによると、bun ci と bun install --frozen-lockfile は、読み込んだ package-lock.json をメモリの上で bun.lock に変えて使うだけで、ファイルには書き出しません。bun.lock を作るには、フラグを付けずに bun install を実行するか、bun pm migrate を実行します。どちらでも、元の package-lock.json は消されずに残ります。同じドキュメントによると、Bun 1.2 からはテキストの bun.lock が標準で、それより前のバイナリの bun.lockb については、bun install --save-text-lockfile --frozen-lockfile --lockfile-only で bun.lock に変えてから、bun.lockb を消す手順が案内されています。
検証環境でも、bun ci のあとのフォルダにあったのは package.json、package-lock.json、node_modules の3つで、bun.lock はできていませんでした。





