Yarn 4 を使う手順を検証したのに、記録に残った Yarn の版は 1.22.22 でした。
あとで確かめると、手順の中で使われていたのは Yarn 4 で、ずれていたのは版の聞き方のほうでした。
原因は、corepack が有効な環境では yarn --version の答えが、どのディレクトリで聞いたかによって変わることにありました。
Docker の node:20 イメージで挙動を測り直すと、版を記録するなら聞く場所まで決めておかないといけない理由がよく分かります。
前提(最小限)
私は、技術記事に載せるコマンド例を Docker の node:20 コンテナで自動実行し、そのとき使ったツールの版を記事に添える仕組みを運用しています。
版は、手順を実行する前後にシェルから yarn --version のようなコマンドで聞いて記録していました。
測り直した環境は次のとおりで、確認日は 2026-10-17 です。
- Docker Engine 29.8.0(linux/amd64)
- 手元にあった node:20 イメージ(Debian 12・Node.js v20.20.2)
- corepack 0.34.6
最初に食い違いに気づいた 2026-10-16 にも、node:20 と corepack 0.34.6 の組み合わせで同じ結果を確かめています。
yarn –version は聞く場所で答えが変わる
まず、node:20 イメージには Yarn 1.22.22 が最初から入っています。
# 確認日 2026-10-17・Docker 29.8.0・node:20(Node.js v20.20.2)
docker run --rm node:20 sh -c '
command -v yarn
readlink -f "$(command -v yarn)"
yarn --version
corepack --version'
# /usr/local/bin/yarn
# /opt/yarn-v1.22.22/bin/yarn
# 1.22.22
# 0.34.6
/usr/local/bin/yarn はリンクで、実体はイメージに同梱されたクラシック版の Yarn です。
corepack は Node.js に同梱されたパッケージマネージャーの版の管理役で、package.json の packageManager フィールドに書いた版を取ってきて動かします。
corepack の README によると、Node.js に同梱されているのは 14.19.0 から 25.0.0 の手前までの版です。
Yarn の公式ドキュメントの Corepack のページも、依存関係と同じようにパッケージマネージャー自体の版も固定すべきだとして、corepack を勧めています。
同じページには、corepack は corepack enable を実行するまで有効にならないとも書かれています。
実際に、packageManager に yarn@4.9.4 と書いたディレクトリでも、corepack enable の前に聞くと 1.22.22 が返り、corepack のキャッシュも作られませんでした。
corepack enable のあとに同じことをすると、結果が変わります。
docker run --rm -e COREPACK_ENABLE_DOWNLOAD_PROMPT=0 node:20 sh -c '
corepack enable
readlink -f "$(command -v yarn)"
mkdir -p /work/app && cd /work/app
echo "{\"packageManager\":\"yarn@4.9.4\"}" > package.json
yarn --version
cd / && yarn --version'
# /usr/local/lib/node_modules/corepack/dist/yarn.js
# 4.9.4
# 1.22.22
command -v yarn が返すパスは同じ /usr/local/bin/yarn のままで、リンクの先だけが corepack の yarn.js に置き換わっています。
リンクを最後までたどって実体のパスを出す readlink -f は、別の記事で整理しました。
このとき yarn は corepack のシム(本物のコマンドの代わりに置かれ、どの版を動かすかを振り分ける小さなプログラム)になり、実行したディレクトリのプロジェクトに書かれた packageManager を見て版を選びます。
| どこで聞いたか | 返った版 |
|---|---|
corepack enable 前・packageManager のあるディレクトリ | 1.22.22(イメージ同梱の版) |
corepack enable 後・packageManager: yarn@4.9.4 のディレクトリ | 4.9.4 |
corepack enable 後・ルート(/) | 1.22.22(corepack の既定の版) |
README には、パッケージマネージャーが設定されていないプロジェクトでは Known Good Release と呼ぶ既定の版を使うと書かれています。
この環境では、プロジェクトの外で聞いた Yarn の既定の版は 1.22.22でした。
私の仕組みはプロジェクトの外で版を聞いていたので、どの手順でも 1.22.22 が記録されていたわけです。
版を聞くと、聞いた版が入ってくる
corepack 経由の yarn は、手元に無い版を求められるとその場でダウンロードします。
corepack enable のあとにプロジェクトの外で yarn --version を打つと、版を答える前に次の 1 行が出ました。
# 標準出力だけを見る
docker run --rm node:20 sh -c 'corepack enable; cd / && yarn --version 2>/dev/null'
# 1.22.22
# 標準エラー出力だけを見る
docker run --rm node:20 sh -c 'corepack enable; cd / && yarn --version >/dev/null'
# ! Corepack is about to download https://registry.yarnpkg.com/yarn/-/yarn-1.22.22.tgz
この 1 行は標準エラー出力に出るので、標準出力だけを拾えば版の数字だけが残ります。
標準出力と標準エラー出力を分けて拾うリダイレクトの書き方は、別の記事にまとめました。
README によると、この表示は環境変数 COREPACK_ENABLE_DOWNLOAD_PROMPT を 0 にすると出なくなります。
手元でも、COREPACK_ENABLE_DOWNLOAD_PROMPT=0 を付けたコンテナではこの行は出ませんでした。
同じ README には、標準入力が TTY で CI 環境でもないときは、ダウンロードの前に確認を求めるとも書かれています。
見落としやすいのは、版を聞く操作そのものが、環境に版を 1 つ足してしまうことです。
corepack のキャッシュには使った版が残る
corepack は取ってきた版を、キャッシュの v1/yarn/<版>/ というフォルダに置きます。
キャッシュの場所は COREPACK_HOME で変えられ、既定は Windows なら %LOCALAPPDATA%\node\corepack、それ以外なら $HOME/.cache/node/corepack だと README に書かれています。
4.9.4 のプロジェクトで使い、続けてルートでも聞いたコンテナの中は、次のようになっていました。
# 上の 4.9.4 の例と同じコンテナで続けて確認(出力は横に並べ直しています)
ls ~/.cache/node/corepack/v1/yarn/
# 1.22.22 4.9.4
ls -A ~/.cache/node/corepack/v1/yarn/4.9.4/
# .corepack yarn.js
ls -A ~/.cache/node/corepack/v1/yarn/1.22.22/
# .corepack LICENSE README.md bin lib package.json preinstall.js
4.9.4 のフォルダには yarn.js と .corepack しか無く、クラシック版のような package.json はありません。
クラシック版と同じつもりで package.json から版を読む方法は、Yarn 4 のフォルダには使えません。
キャッシュの直下にある lastKnownGood.json には、既定として使う Yarn の版が 1.22.22 と記録されていました。
一方、packageManager: yarn@4.5.0 のプロジェクトで使っただけなら、版のフォルダは 4.5.0 の 1 つだけでした。
キャッシュが空の状態から始めていれば、版のフォルダが 1 つしか無いとき、それが作業で実際に使われた版です。
キャッシュのフォルダ名から版を 1 つに決めて読む
そこで、まずキャッシュのフォルダ名から版を読むように直しました。
package.json の packageManager を読む方法もありますが、corepack enable の前は宣言があっても 1.22.22 が動いていたので、宣言だけでは使われた版の証拠になりません。
決めたことは次の 3 つです。
- 版のフォルダが 1 つだけなら、その版を記録する
- 2 つ以上なら決めつけず、従来の聞き方に戻す(推測した値を載せない)
- キャッシュは、版を聞くより先に見る
3 つ目は、あとから yarn --version を聞くとフォルダが増えてしまうからです。
実際に使っている関数を、名前だけ変えて抜粋します。
corepack_used_version() {
find "${COREPACK_HOME:-$HOME/.cache/node/corepack}/v1/$1" \
-mindepth 1 -maxdepth 1 -type d 2>/dev/null \
| sed -n 's#.*/\([0-9][^/+]*\)[^/]*$#\1#p' \
| sort -u | { read -r a; read -r b; [ -n "$a" ] && [ -z "$b" ] && echo "$a"; }
}
corepack_used_version yarn # 版が 1 つだけなら表示し、それ以外は何も出さない
フォルダ名に + 以降が付く形にも備えて、+ から後ろは落として読んでいます。
ただ、その形のフォルダは実機では見ておらず、テストで確かめただけです。
node:20 のコンテナで、corepack enable のあとに場面を変えて呼んだ結果は次のとおりでした(2026-10-17)。
corepack enable のあとにしたこと | 版のフォルダ | 関数の出力 |
|---|---|---|
| まだ yarn を使っていない | なし | 何も出ない |
yarn@4.5.0 のプロジェクトで yarn を使った | 4.5.0 | 4.5.0 |
続けてプロジェクトの外で yarn --version を聞いた | 1.22.22・4.5.0 | 何も出ない |
packageManager の無いプロジェクトで yarn を使った | 1.22.22 | 1.22.22 |
COREPACK_HOME=/tmp/cphome を付けて 4.5.0 のプロジェクトで使ったときも、関数は 4.5.0 を返しました。
直したあとに記録された版
直したあと、Yarn を使う 3 本の記事の手順を検証し直しました。
| 記事の手順 | 記録された版 |
|---|---|
| Yarn 4 の Plug'n'Play を扱う手順 | 4.9.4 |
--immutable を扱う手順 | 4.5.0 |
yarn: command not found を扱う手順 | 1.22.22 |
3 本目が 1.22.22 なのは、corepack の既定がクラシック版だからです。
3 本とも、手順で実際に使われた版どおりの記録になりました。
最後に
ツールの版は、どのディレクトリで、どのシムを通して聞いたかで答えが変わります。
yarn --version が答えるのはその場所で選ばれる版で、作業で使われた版とは限りません。
記録したいのが作業で実際に使われた版なら、実行のあとに残る痕跡から読むほうが確実です。
corepack の場合、その痕跡がキャッシュの版フォルダでした。
版を記録する仕組みを作るときは、何を聞くかと一緒に、どこで聞くかまで決めておくと食い違いを防げます。
以上です。











コメントを残す