# Puppeteer で利用する Chrome のオフラインインストール方法

Puppeteer でオフライン環境において Chrome を利用するための手順を整理したドキュメントです。

# 1 概要

Puppeteer は Node.js 上で動作するヘッドレスブラウザ自動化ツールです。通常、`puppeteer` パッケージをインストールすると Chrome for Testing が自動的にダウンロードされますが、オフライン環境ではこの自動ダウンロードが利用できません。

本ドキュメントでは、オフライン環境で Puppeteer を利用するための複数のアプローチを説明します。

# 2 Puppeteer パッケージの種類

Puppeteer には 2 種類のパッケージがあります。

## 2.1 puppeteer (フルパッケージ)

    npm i puppeteer

インストール時に Chrome for Testing (約 170MB macOS、約 282MB Linux、約 280MB Windows) と chrome-headless-shell バイナリを自動的にダウンロードします。

## 2.2 puppeteer-core (ライブラリのみ)

    npm i puppeteer-core

ブラウザをダウンロードせず、ライブラリのみをインストールします。既存の Chrome または Chromium を使用する場合に適しています。

# 3 オフラインインストールの方法

## 3.1 方法 1: [@puppeteer/browsers] CLI ツールを使用

`@puppeteer/browsers` CLI ツールを使用して、事前に Chrome for Testing をダウンロードする方法です。

### 3.1.1 最新の安定版をダウンロード

    npx @puppeteer/browsers install chrome@stable

### 3.1.2 特定のバージョンをダウンロード

    npx @puppeteer/browsers install chrome@116.0.5793.0

### 3.1.3 マイルストーンの最新版をダウンロード

    npx @puppeteer/browsers install chrome@117

### 3.1.4 ダウンロード先

Puppeteer v19.0.0 以降、ブラウザは `$HOME/.cache/puppeteer` にユーザーグローバルにキャッシュされます。このキャッシュディレクトリは複数のインストール間で共有されるため、一度ダウンロードすればオフライン環境で再利用できます。

Linux の場合:

    $HOME/.cache/puppeteer/chrome/linux-142.0.7444.175/chrome-linux64/chrome

Windows の場合:

    %USERPROFILE%\.cache\puppeteer\chrome\win64-137.0.7151.70\chrome-win64\chrome.exe

## 3.2 方法 2: 環境変数を使用したスキップとキャッシュ管理

### 3.2.1 Chrome の自動ダウンロードをスキップ

    export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
    npm install puppeteer

### 3.2.2 キャッシュディレクトリのカスタマイズ

    export PUPPETEER_CACHE_DIR=/path/to/custom/cache
    npm install puppeteer

デフォルトのキャッシュディレクトリは `os.homedir()/.cache/puppeteer` です。

### 3.2.3 その他の環境変数

- `PUPPETEER_TMP_DIR`: Puppeteer が一時ファイルを作成するディレクトリを指定
- `HTTP_PROXY`、`HTTPS_PROXY`、`NO_PROXY`: ブラウザのダウンロードと実行時に使用する HTTP プロキシ設定

## 3.3 方法 3: 設定ファイルによる管理

プロジェクトのルートディレクトリに `.puppeteerrc.cjs` を作成し、キャッシュディレクトリを指定します。

    const { join } = require('path');

    module.exports = {
      cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
    };

注意: Puppeteer の設定ファイルと環境変数は `puppeteer-core` では無視されます。

## 3.4 方法 4: Chrome for Testing を手動でダウンロード

Chrome for Testing は Google が提供する自動化テスト専用の Chrome ビルドです。

### 3.4.1 JSON API エンドポイント

Chrome for Testing の各バージョンは JSON API から取得できます。

    curl https://googlechromelabs.github.io/chrome-for-testing/LATEST_RELEASE_STABLE

    curl https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json

    curl https://googlechromelabs.github.io/chrome-for-testing/latest-patch-versions-per-build-with-downloads.json

### 3.4.2 直接ダウンロード URL パターン

Chrome for Testing バイナリは以下の URL パターンで直接ダウンロードできます。

    https://storage.googleapis.com/chrome-for-testing-public/{VERSION}/{PLATFORM}/{BINARY}-{PLATFORM}.zip

#### 3.4.2.1 対応プラットフォーム

- `linux64`
- `mac-arm64`
- `mac-x64`
- `win32`
- `win64`

#### 3.4.2.2 ダウンロード例

    curl -O https://storage.googleapis.com/chrome-for-testing-public/118.0.5962.0/linux64/chrome-linux64.zip

    unzip chrome-linux64.zip

# 4 オフライン環境での使用方法

## 4.1 executablePath を指定して起動

手動でダウンロードした Chrome や既存の Chrome を使用する場合は、`executablePath` オプションで実行パスを指定します。

    const puppeteer = require('puppeteer');

    const browser = await puppeteer.launch({
      executablePath: '/path/to/chrome/executable',
    });

    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();

## 4.2 キャッシュディレクトリから自動検出

Puppeteer v19.0.0 以降、ブラウザは `~/.cache/puppeteer` から自動的に検出されます。事前にこのディレクトリに Chrome をダウンロードしておけば、`executablePath` を指定せずに使用できます。

    const puppeteer = require('puppeteer');

    // キャッシュディレクトリから自動的に Chrome を検出
    const browser = await puppeteer.launch();
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();

# 5 オフラインインストールの推奨フロー

以下の手順で、オンライン環境で Chrome をダウンロードし、オフライン環境で使用することを推奨します。

## 5.1 オンライン環境での準備

    cd /path/to/your/project

    export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
    npm install puppeteer

    mkdir -p .cache/puppeteer

    export PUPPETEER_CACHE_DIR=$(pwd)/.cache/puppeteer
    npx @puppeteer/browsers install chrome@stable

## 5.2 オフライン環境での使用

    cd /path/to/your/project

    export PUPPETEER_CACHE_DIR=$(pwd)/.cache/puppeteer

    node your-script.js

または、`.puppeteerrc.cjs` を使用してキャッシュディレクトリを指定します。

    // .puppeteerrc.cjs
    const { join } = require('path');

    module.exports = {
      cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
    };

# 6 バージョン互換性

各 Puppeteer バージョンは単一の Chrome バージョンに対応しています。互換性を確保するため、Puppeteer がインストールされているプロジェクトで以下のコマンドを実行することを推奨します。

    npx puppeteer browsers install chrome

このコマンドは、インストールされている Puppeteer バージョンに対応する Chrome バージョンを自動的にダウンロードします。

# 7 トラブルシューティング

## 7.1 Chrome が見つからないエラー

    Error: Could not find Chrome

このエラーが発生した場合、以下を確認してください。

- Chrome がキャッシュディレクトリにダウンロードされているか
- `PUPPETEER_CACHE_DIR` 環境変数が正しく設定されているか
- `.puppeteerrc.cjs` の `cacheDirectory` が正しいパスを指しているか
- `executablePath` を明示的に指定しているか

## 7.2 ネットワークエラー

オンライン環境でダウンロード時にネットワークエラーが発生する場合、プロキシ設定を確認してください。

    export HTTP_PROXY=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    npx @puppeteer/browsers install chrome@stable

# 8 参考資料

- Puppeteer Installation Guide
- Puppeteer Configuration Guide
- [@puppeteer/browsers] NPM Package
- Chrome for Testing: reliable downloads for browser automation
- Chrome for Testing JSON API
- Stack Overflow: Use puppeteer-core and installing chromium manually