playwright-cli のローカルインストールがうまくいかない

テック

備忘録

2026年5月4日

💡

一言要約： playwrightプロジェクトにplaywright-cliをローカルインストールしても依存解決がうまくいかなかったので、公式に言われた通りの使い方をした方がいい

背景

playwright-cliを使いたかった
公式のinstall方法としてnpmによるグローバルインストールが紹介されていたnpm install -g @playwright/cli@latest

問題

ローカルのpnpmプロジェクトですでにplaywrightを利用していたので、無視してpnpm install @playwright/cli で行けるのでは？と思い強行
shell
```
Packages: +3
+++
Progress: resolved 1238, reused 1091, downloaded 3, added 3, done

dependencies:
+ @playwright/cli 0.1.11
```
インストールはいけた

パス通ってるかな？

shell

$ pnpm playwright-cli
node:internal/modules/cjs/loader:692
      throw e;
      ^

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './lib/tools/cli-client/program' is not defined by "exports" in /Users/michika.kurotaka/Repos/global/delish-web-global/node_modules/.pnpm/node_modules/playwright-core/package.json
    at exportsNotFound (node:internal/modules/esm/resolve:314:10)
    at packageExportsResolve (node:internal/modules/esm/resolve:662:9)
    at resolveExports (node:internal/modules/cjs/loader:685:36)
    at Module._findPath (node:internal/modules/cjs/loader:752:31)
    at Module._resolveFilename (node:internal/modules/cjs/loader:1441:27)
    at defaultResolveImpl (node:internal/modules/cjs/loader:1066:19)
    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1071:22)
    at Module._load (node:internal/modules/cjs/loader:1242:25)
    at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
    at Module.require (node:internal/modules/cjs/loader:1556:12) {
  code: 'ERR_PACKAGE_PATH_NOT_EXPORTED'
}

Node.js v24.14.0

なんだかよくなさそうなエラー

調べて分かった原因

@playwright/cli 0.1.11 は playwright-core/lib/tools/cli-client/program を直接 require() している。
@playwright/cli 0.1.11 自身は playwright-core を直接依存に持たず、playwright 1.60.0-alpha-1777669338000 に依存している。
既存プロジェクトには @playwright/test 1.58.2 があり、その経路で playwright-core 1.58.2 が入っていた。
playwright-core 1.58.2 の exports には ./lib/tools/cli-client/program がない。

要するに「既存の Playwright 依存があるプロジェクトに @playwright/cli をローカル install したことで、互換性のない playwright-core が混ざってしまった」

教訓

方式	例	どこに入るか	`package.json` 変更	向いている用途	今回との関係
ローカル install	`pnpm add -D @playwright/cli`	そのプロジェクトの `node_modules`	される	プロジェクト依存として継続利用したいとき	既存 `playwright` 依存と混ざって壊れた
グローバル install	`npm install -g @playwright/cli`	PC 全体の共有領域	されない	どのディレクトリでも同じ CLI を使いたいとき	プロジェクト依存と混ざりにくいので回避しやすい
`npx`	`npx @playwright/cli --help` または `npx playwright-cli --help`	一時環境、または既存ローカルを利用	通常されない	1 回試したいとき、隔離実行したいとき	グローバルほど重くなく、安全寄り
`pnpm dlx`	`pnpm dlx @playwright/cli@latest --help`	一時環境	されない	`pnpm` 利用者が単発 CLI を安全に使いたいとき	今回はいちばん相性がよい回避策

パッケージ管理周りの理解が浅いまま「なんかいい感じに依存解決して動いてくれるだろ」と考えて無理やりローカルに入れるのは良くない
そもそもplaywright-cliはAIエージェント経由でskillsと組み合わせて使う想定のため、元からグローバルでインストールしたほうが今回は好ましかった

追記

素直に npx install -g @playwright/cli@latest をしたのにccはnpx —no-install でやっている…

shell

⏺ Header / Footer / Breadcrumb の修正内容を把握しました。次にdevサーバーを起動し、playwright-cliでUI確認します。

⏺ Bash(curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/ || echo "not running")
  ⎿  200

⏺ Bash(npx --no-install playwright-cli --version 2>&1 || which playwright-cli)
  ⎿  0.1.11

playwright-cli install --skillsで入れるSKILL.mdにも書いてあった（パスが通ってなかったのはセッション起動タイミングの問題かも

shell

## Installation

If global `playwright-cli` command is not available, try a local version via `npx playwright-cli`:

```bash
npx --no-install playwright-cli --version
```

When local version is available, use `npx playwright-cli` in all commands. Otherwise, install `playwright-cli` as a global command:

```bash
npm install -g @playwright/cli@latest
```