npm publish とは、手元のパッケージを固めて npm の registry に送り、名前で install できるようにする npm の命令です。
- npm publish が何を送り、同じ版を出し直せない理由と、npm pack・npm view・npm dist-tag・npm deprecate の役目
- GitHub Actions から Trusted Publisher（OIDC）で公開する形と、ENEEDAUTH を撃つ前に見抜く確かめ方
- publish が成功したのに registry で 404 のまま、手元の pack が配る物と違った、2 段階認証で口座が止まった、など当社の記録
当社は、自社の CLI のパッケージとその兄弟のパッケージを、AIエージェント の席に GitHub Actions から公開させています。席は命令の出力を文字どおりに読むので、「成功と出たのに見えない」「dry-run が緑なのに本番で落ちる」といった npm の癖が、そのまま判断の誤りになりました。この頁は npm の公式の文書の定義と、その記録を並べたものです。
npm publish は何を送るか：版は一度きり、既定は latest
npm publish が送れるのは、package.json の在るフォルダ、固めた tarball、<名前>@<版> などです。名前と版の組は一度しか公開できず、unpublish しても同じ組はもう使えません。公開すると、--tag を付けない限り latest の印がその版に付きます（npm-publish・npm-dist-tag の文書）。
| 命令 | 何をするか（公式の文書） | 当社が使う場面 |
|---|---|---|
npm publish | パッケージを registry に公開する。--dry-run は何も変えずに、何をするかだけを出す | 本番の公開 |
npm pack | パッケージを <名前>-<版>.tgz に固めて手元に置く | 配る物の中身を確かめる |
npm view | registry に在るパッケージの情報を出す。<名前>@<版> でその版に絞れる | 公開されたか・誰が出したかを見る |
npm dist-tag | latest などの印を版に付ける・外す・並べる | 利用者に届く版を切り替える |
npm deprecate | 版に警告文を付け、install する人に見せる。持ち主でないと撃てない | 壊れた版を知らせる |
出典: docs.npmjs.com「npm-publish」https://docs.npmjs.com/cli/v11/commands/npm-publish ・「npm-pack」https://docs.npmjs.com/cli/v11/commands/npm-pack ・「npm-view」https://docs.npmjs.com/cli/v11/commands/npm-view ・「npm-dist-tag」https://docs.npmjs.com/cli/v11/commands/npm-dist-tag ・「npm-deprecate」https://docs.npmjs.com/cli/v11/commands/npm-deprecate （どれも 2026-11-07 に確認）。
入るファイルは、既定では全部です。package.json の files が在ればそこに書いた物だけ、.npmignore（無ければ .gitignore）に合う物は外れます。中身を前もって見るには npm pack --dry-run を使う、と公式の文書は書いています（npm-publish の文書・2026-11-07 に確認）。
npm pack は prepublishOnly を走らせない：配る物はビルドの後に測る
npm の文書では、publish のときに走る script は prepublishOnly・prepack・prepare・postpack・publish・postpublish の順で、pack のときは prepack・prepare・postpack だけです。prepublishOnly は「npm publish のときだけ」走ります（npm-scripts の文書・2026-11-07 に確認）。
当社はこれを知らずに一度止まりました。手元で npm pack した中身に、ビルドで作られるはずのファイルが 0 件で、「このまま公開すると利用者の起動が全部落ちる」と判断して公開を止めました（社の実測 2026-09-25）。ところがビルドは prepublishOnly に入っていたので、手元の pack は配る物とは別物でした。CI の dry-run の一覧にはそのファイルが 3.3kB で在り、手元でもビルドしてから pack すると 1 件入り、起動の試験は終了コード 0 でした（社の実測 2026-09-25）。
ビルドを prepublishOnly に置いているパッケージで中身を確かめるときは、先にビルドを撃ってから npm pack します。prepack か prepare にビルドを置けば、pack と publish の中身が揃います（npm-scripts の文書の順による）。
公開のログの + の行は、送った数ではない
npm publish が通ると、ログに + <名前>@<版> の行が出ます。当社は 1 回の流れのログで + の行を 3 本数え、「3 本受け取られた」と読み違えました。うち 2 本は dry-run で、行に「(dry-run)」と付いていました（社の実測 2026-09-25）。
dry-run は何も変えずに、何をするかだけを出す印です（npm-publish の文書・2026-11-07 に確認）。実際に送った数は、+ の行ではなく、入力の dry_run の値と「(dry-run)」の有無で数えます（社の実測 2026-09-25）。
npm publish 404：成功と出たのに registry に無い時は、審査の保留を疑う
2026-09-25、npm publish が + <名前>@<版> を出して終了コード 0 で終わったのに、その版は registry で 404 のままでした。ログには「Your package is being processed and may take a few minutes to become available」と出ていました（社の実測 2026-09-25）。npm は 2026-07-28 から公開時にマルウェアの検査をしていて、受け取った版を「そのまま公開」「人が審査する保留」「ブロック」に振り分けていました。この版は保留に入っていました（社の実測 2026-09-25）。なお、この検査と保留は、今日確かめた公式の文書の頁には書かれていませんでした。
| 保留の間に撃った物 | 返ってきた物 |
|---|---|
同じ源・同じ版をもう 1 回 npm publish | E409「Cannot publish over previously staged version」 |
npm stage list | 0 件 |
npm view <名前>@<版> | 404 |
出典: 社の実測 2026-09-25。
当社は 30 分 404 が続いた所で「ブロックされた」と断定しましたが、誤りでした。その版は 21〜56 分後に公開されました（社の実測 2026-09-25）。2026-10-27 に出した版も、それぞれ約 26 分・約 19 分保留されてから公開されています（社の実測 2026-10-27）。
保留かどうかは、npm stage list の 0 件では分かりません。同じ源・同じ版をもう 1 回 publish して E409 が返れば、registry はその版を受け取って持っています（社の実測 2026-09-25）。
npm publish を GitHub Actions から：Trusted Publisher（OIDC）
Trusted Publisher は、長く生きる npm の token の代わりに OIDC で CI から公開する仕組みです。公式の文書の要点は次のとおりです。
| 項目 | 公式の文書の内容 |
|---|---|
| 使える CI | GitHub Actions（GitHub が持つ runner）・GitLab CI/CD（GitLab.com の共有 runner）・CircleCI（cloud）。self-hosted runner はまだ対象外 |
| 要る版 | npm CLI 11.5.1 以上・Node 22.14.0 以上 |
| workflow の権限 | GitHub Actions では id-token: write が要る |
| 登録 | npmjs.com のパッケージの設定の「Trusted Publisher」で、口座・リポ・workflow のファイル名を入れる。保存の時には確かめず、誤りは publish の時に初めて出る |
| 数と期限 | 1 つのパッケージに 10 個まで。新しい登録は 2 日以内に 1 度 publish が通らないと切れる |
| dist-tag | 「Allow npm dist-tag」を別に選ばないと、OIDC からは dist-tag を触れない（既定は無効） |
出典: docs.npmjs.com「Trusted publishing for npm packages」https://docs.npmjs.com/trusted-publishers （2026-11-07 に確認）。
GitHub Actions の分と料金の数え方は GitHub Actions の料金の頁に、CI に渡す鍵の置き場は Secret Manager の頁に書いています。
ENEEDAUTH：dry-run は緑でも、本番は認証で落ちる
2026-09-26、GitHub Actions からの本番の publish が ENEEDAUTH で落ちました。同じ workflow の dry-run は緑でした。dry-run は認証を測っていなかった、ということです（社の実測 2026-09-26）。そのパッケージは Trusted Publisher が未登録で、それまでの版は人の口座から手元で出していました（社の実測 2026-09-26）。
撃つ前の確かめ方は 1 つです。npm view <パッケージ>@<最新の版> _npmUser を見て、出した者が GitHub Actions でなければ、workflow の本番はまだ通ったことが無く、落ちると見込みます（社の実測 2026-09-26）。_npmUser の欄は、今日確かめた npm-view の文書には書かれていませんでした。
npm 2fa：リカバリーコードでログインすると、口座が 72 時間止まる
公式の文書では、リカバリーコードでログインすると口座に 72 時間の保留がかかり、その間は publish・token の作成・口座の設定の変更ができません。リカバリーコードは 1 つにつき 1 回しか使えず、2 段階目の機器を失った時に口座を取り戻す唯一の手段だ、とも書いています（2 段階認証の文書・2026-11-07 に確認）。
当社はこれを踏みました。Trusted Publisher の登録の画面がセキュリティキーでの確認しか受け付けず、CLI でリカバリーコードを使ってログインしたところ、口座が 72 時間の一時停止になり、期限まで解く操作はありませんでした。CLI からの登録も EOTP（Web での確認）に落ちて通りませんでした（社の実測 2026-10-05）。
| 停止の間 | 結果 |
|---|---|
| GitHub Actions の Trusted Publisher（OIDC）からの publish | 通った（その版の _npmUser が GitHub Actions） |
| 口座の token での手元の publish | 止まった |
| 口座の設定の変更 | 止まった |
出典: 社の実測 2026-10-05。
それ以来、リカバリーコードはキーを本当に失った時以外には使いません（社の実測 2026-10-05）。OIDC の経路を先に通しておくと、口座が止まっても公開は続けられます。
npm dist-tag と npm deprecate で戻す前に、戻しの道を確かめる
壊れた版を出した時の戻し方は、latest を前の版へ付け替える（dist-tag）か、壊れた版に警告を付ける（deprecate）のが筋です。ただし deprecate は持ち主でないと撃てず（npm-deprecate の文書・2026-11-07 に確認）、OIDC から dist-tag を触るには別の許可が要ります（trusted-publishers の文書・2026-11-07 に確認）。
当社の自動の席には、deprecate と dist-tag の付け替えに要る持ち主の資格が無かったので、「前の版の中身を、次の版の番号で出し直す」ことを戻しの手にしました。公開から利用者に届くまでは約 56 分を見込みました（社の実測 2026-10-30）。審査の保留があるので、戻しも即座には届きません。
戻しの道を撃つ前に確かめる時、npm dist-tag add を今と同じ版に撃っても何も変わらず（no-op）、道が開いているかは測れませんでした。そこで registry へ「latest を同じ版に向ける」無害な書き込みを撃ち、token ありで 204・token なしで 401 が返るのを見て、戻しの道が開いていると確かめました（社の実測 2026-10-24）。
npm view で古い版を見る時は tarball を取る
npm view <パッケージ>@<古い版> readme は、当社の手元では古い版ではなく最新版の README を返しました（社の実測 2026-10-27）。npm-view の文書は、版を付けるとその版に絞って出すと書いていますが、readme の欄については何も書いていません（2026-11-07 に確認）。
古い版の中身と比べる時は、その版の tarball を取って中を見ます。npm pack <パッケージ>@<版> は registry から取った tarball を手元に置きます（npm-pack の文書・2026-11-07 に確認）。
同じ群の道具の頁として、pnpm の頁も今日まとめています。
よくある質問
npm publish が成功したのに npm view で 404 になる。失敗した？
当社の記録では、公開時の検査で保留に入っていただけで、21〜56 分後に公開されました（社の実測 2026-09-25）。同じ源・同じ版をもう 1 回 publish して E409 が返れば、registry は受け取っています。番号を上げて出し直す前に待ちます。
ENEEDAUTH は何が原因？
当社では、本番の publish が認証を持たずに撃たれた時に出ました。GitHub Actions から出したパッケージに Trusted Publisher が未登録だったのが原因で、dry-run は緑でした（社の実測 2026-09-26）。npm view <パッケージ>@<最新の版> _npmUser が GitHub Actions かどうかで、撃つ前に見抜けます。
npm pack と npm publish の中身は同じ？
走る script が違います。prepublishOnly は publish の時だけ走り、pack では走りません（npm-scripts の文書・2026-11-07 に確認）。ビルドを prepublishOnly に置いているなら、先にビルドしてから pack しないと、配る物と違う中身を見ることになります。
npm の 2 段階認証でリカバリーコードを使うとどうなる？
口座に 72 時間の保留がかかり、publish・token の作成・設定の変更ができなくなります（2 段階認証の文書・2026-11-07 に確認）。当社の記録では、その間も Trusted Publisher（OIDC）からの publish は通りました（社の実測 2026-10-05）。
公開した版を取り消したい時は？
持ち主なら npm deprecate で警告を付けるか、npm dist-tag で latest を前の版へ戻します。当社の自動の席には持ち主の資格が無かったので、前の版の中身を次の版の番号で出し直し、届くまで約 56 分を見込みました（社の実測 2026-10-30）。
出典
- docs.npmjs.com「npm-publish」https://docs.npmjs.com/cli/v11/commands/npm-publish （2026-11-07 に確認）
- docs.npmjs.com「Trusted publishing for npm packages」https://docs.npmjs.com/trusted-publishers （2026-11-07 に確認）
- docs.npmjs.com「npm-pack」https://docs.npmjs.com/cli/v11/commands/npm-pack （2026-11-07 に確認）
- docs.npmjs.com「scripts」https://docs.npmjs.com/cli/v11/using-npm/scripts （2026-11-07 に確認）
- docs.npmjs.com「npm-dist-tag」https://docs.npmjs.com/cli/v11/commands/npm-dist-tag （2026-11-07 に確認）
- docs.npmjs.com「npm-view」https://docs.npmjs.com/cli/v11/commands/npm-view （2026-11-07 に確認）
- docs.npmjs.com「npm-deprecate」https://docs.npmjs.com/cli/v11/commands/npm-deprecate （2026-11-07 に確認）
- docs.npmjs.com「Configuring two-factor authentication」https://docs.npmjs.com/configuring-two-factor-authentication （2026-11-07 に確認）
- 社の実測 2026-09-25・2026-09-26・2026-10-05・2026-10-24・2026-10-27・2026-10-30（自社の CLI のパッケージと兄弟のパッケージの公開の記録）
ブルーランプ 記事の編集部／更新日 2026-11-07