> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/gaidopage/local-preview-and-deploy-page.md).

# Pageをローカル確認してデプロイする

開発したPageは、ローカルでブラウザ向け成果物を確認してからStudioへ初回登録します。Studio画面でZIPを選ぶ方法と、Studio CLIでZIPまたは成果物ディレクトリをデプロイする方法があります。開発サーバーでの表示と、利用者の入口での動作は別々に確認してください。

この記事では初回登録までを扱います。既存Pageの更新、切戻し、バージョン履歴は[Pageのバージョンを管理する](/rupageskillrissu/manage-page-versions.md)を参照してください。

## 関連記事

* [Pageのソース構成とランタイム](/gaidopage/page-source-structure-and-runtime.md)
* [画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)
* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)
* [CLI Pages](/clirifarensu/cli-pages.md)

## 始める前に

* 対象のProject、Page名、利用者、初回登録で公開してよい範囲を確認します。画面からの初回登録で、既存のPageと同名と判定された場合は、「新しいバージョンを追加」の確認が出ます。新規作成か更新かを確認してから進めます。
* ローカルのNode.jsは22以上にし、CLIはSDKと同じ完全な版に固定します。SDK/CLIの版と導入は[開発環境・バージョン・互換性](/gaidobito/dev-environment-and-versions.md)を確認してください。
* `package.json` にあるスクリプトを確認します。Studioが登録時に依存関係を導入したり、`npm run build`を実行したりするわけではありません。成果物はローカルで生成します。
* HTML、JavaScript、CSS、画像など、ブラウザへ配る成果物だけを用意します。APIキー、トークン、Secret値、個人情報を成果物、ソースマップ、公開用環境変数に含めません。

> `npm run dev`は開発サーバー用のことがあります。ローカルで表示できても、そのサーバーが行う変換・プロキシ・環境変数に依存したままでは、ZIP登録後に表示できない場合があります。可能ならビルド済み成果物を確認します。

## 1. ローカルでビルドし、表示を確認する

まず、プロジェクトで定義された依存関係の導入とビルドを実行します。コマンド名はプロジェクトごとに異なるため、次は`package.json`に`build`スクリプトがある場合の例です。

```bash
npm install
npm run build
```

開発中の画面確認には、`dev`スクリプトが定義されている場合に次を使えます。

```bash
npm run dev
```

ビルド結果を本番に近い形で確認するスクリプトが定義されている場合は、そのコマンドも実行します。たとえば`preview`があるプロジェクトでは次のようになります。

```bash
npm run preview
```

表示されたローカルURLをブラウザで開き、初期表示、画面遷移・アセット読込み、代表操作、入力・登録・送信の結果を確認します。登録・外部送信を伴う操作は、検証用データと検証先を使い、結果が不明な処理を繰り返さないでください。

| 確認項目 | 確認すること                                                 |
| ---- | ------------------------------------------------------ |
| 初期表示 | 空白画面、コンソールエラー、読込み失敗がないこと                               |
| アセット | JavaScript、CSS、画像、フォントなどがビルド済みの相対パスで読めること              |
| 外部依存 | 開発サーバー専用のプロキシ、ローカル環境変数、履歴APIフォールバックだけに依存していないこと        |
| 秘密情報 | ブラウザの開発者ツールで確認できるHTML、JavaScript、リクエスト、ログにAPIキー等が出ないこと |
| 業務処理 | 保存先・送信先などで結果を確認できること                                   |

> すべてのPageで`dev`または`preview`が使えるとは限りません。定義がなければ追加を前提にせず、採用しているツールチェーンでビルド済みの静的成果物を確認してください。

## 2. 配布用ZIPを作る

ZIPのルートには、最初に開くHTMLと参照されるアセットを置きます。`dist`や`build`などの出力フォルダー自体をZIPに重ねず、その**中身**をルートにします。次は出力先が`dist`の場合の例です。

```bash
cd dist
zip -r ../page-release.zip .
cd ..
unzip -l page-release.zip
```

`unzip -l`の一覧で、最初に表示するHTMLと必要なアセットがZIPのルートから参照できることを確認します。元ソース、`node_modules`、`.git`、`.jai-studio`、出力フォルダーを包む親ディレクトリを混在させないでください。現在・親ディレクトリを表すパスは登録できません。

ZIPは100MB以下、エントリ数は5,000件以下、展開後の合計は200MB以内にします。詳しい除外対象と構造条件は[Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)を確認してください。

## 3. Studio画面から初回登録する

1. 対象Projectの「ページ」を開き、「ZIPをアップロード」を選択します。
2. 「ページをアップロード」で「ZIPファイルを選択」を選ぶか、「ここにZIPファイルをドロップ」へZIPを置きます。
3. ファイル名と対象Projectを確認し、「アップロード」を選択します。「ファイルをアップロードしています」の間は画面を閉じません。
4. 同名のページが見つかった場合は、確認画面の説明を読みます。「新しいバージョンを追加」は、既存ページの新しい版を追加して有効にする操作です。初回登録のつもりで既存Pageを更新しないでください。
5. 「アップロードが完了しました。」を確認し、ページ一覧に登録結果が現れることを確認します。
6. 対象を開き、登録した画面と代表操作を確認します。

「ページをアップロードする権限がありません」と表示された場合は、ProjectまたはPageの管理担当者へ確認します。容量・構造エラーのときは、画面の制限を回避するために不要なファイルを推測で残さず、ZIPを展開して構成を見直します。詳細な画面操作は[画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)を参照してください。

## 4. CLIで初回デプロイする

CLIを使う場合は、先にProject APIキーを安全に設定します。キーをコマンド引数へ書くとシェル履歴やプロセス一覧に残るため、対話入力、標準入力、または`JAI_STUDIO_API_KEY`を使います。次は対話入力でプロファイルを作る例です。

```bash
npm install --global @japan-ai-inc/studio-sdk@0.11.0
jai-studio config set my-project
jai-studio --profile my-project pages deploy ./dist --name "受注ダッシュボード" --json
```

`pages deploy`にはZIPファイルまたはディレクトリを渡せます。ディレクトリを渡すとCLIがZIPを作成するため、完成済みの`./dist`を指定します。初回デプロイでは`--name`で表示名を指定できます。成功時のJSONには、Page ID、`studioUrl`、`runtimeUrl`、バージョン、ファイル数、日時、再ビルド要求の有無が返ります。

`runtimeUrl`が`null`の場合は、`studioUrl`から対象Pageを開いて確認します。URLやPage IDは安全な場所に記録し、APIキーは記録しません。

> ディレクトリを初回デプロイすると、CLIはそのディレクトリ内の`.jai-studio/page.json`へPage IDなどを保存します。次回、同じディレクトリを`--page-id`なしで指定すると、そのIDを使う更新になります。初回デプロイ用の成果物を不用意に再利用しないでください。既存Pageの更新は[Pageのビルド・起動・更新](/gaidopage/page-build-start-update.md)および[Pageのバージョンを管理する](/rupageskillrissu/manage-page-versions.md)で確認します。

ZIPを自分で作成済みの場合も、同じコマンドで指定できます。ZIP入力でメタデータを保存する場合だけ`--save-page-metadata`を使用します。

```bash
jai-studio --profile my-project pages deploy ./page-release.zip \
  --name "受注ダッシュボード" \
  --save-page-metadata ./page-metadata.json \
  --json
```

## 5. アクセスURLと利用者の入口を確認する

CLIの成功や「アップロードが完了しました。」だけで、利用者のアクセス確認は完了しません。Studioで対象Pageを開き、ページのメニューから「アクセス設定」を確認します。

1. 利用者に必要な「アクセスモード」を選び、「アクセス設定を保存しました。」を確認します。
2. 「サインイン任意」または「匿名アクセス」では、表示される「公開URL」を確認します。URLを共有するとStudioにサインインせずアクセスできるため、表示データと実行可能な処理を確認してから案内します。
3. 「外部顧客認証」では、設定済みの外部認証接続を選びます。保存後、「アクセスURL」が有効であることを確認します。このURLは、設定の保存と公開済みバージョンの存在後に有効になります。
4. 想定する利用者の入口（Studio内、公開URL、アクセスURL）で開き、表示、権限、代表操作、保存先または送信先の結果を確認します。

Pageを開けたことは、データ取得、認証、外部連携、更新まで成功する保証ではありません。実際の利用時の確認項目は[Pageから業務を進める](/u/work-with-pages.md)を参照してください。

## チェックリスト

* [ ] ローカルでビルド済み成果物を表示し、代表操作と結果を確認した
* [ ] ZIPのルートにHTMLと必要なアセットを置き、秘密情報を含めていない
* [ ] ZIPの容量、エントリ数、展開後サイズ、構造を確認した
* [ ] UIまたはCLIのどちらで初回登録するかを決め、対象ProjectとPage名を照合した
* [ ] CLIではAPIキーを引数に書かず、正しいプロファイルまたは安全な環境変数を使った
* [ ] デプロイ後に`studioUrl`またはPageカードからPageを開いた
* [ ] 「アクセス設定」と、公開URLまたはアクセスURLの共有範囲を確認した
* [ ] 想定する利用者の入口から、画面と業務処理の結果を確認した

## うまくいかない場合

| 状況                     | 確認・対応                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| ローカルでは動くが登録後は白い画面になる   | ビルド済みHTMLとアセットの相対パス、開発サーバーだけにあるプロキシや環境変数への依存を確認します。ZIPを展開してルート構成を確認します。                              |
| ZIPが受け付けられない           | 100MB、5,000エントリ、展開後200MB、ZIP内のパス、除外対象を確認します。画面のエラーとZIP一覧を添えて相談します。                                   |
| CLIが認証できない             | `jai-studio config show`で対象プロファイルと接続先を確認します。表示されるマスク済みのキーを再利用せず、保管済みの実値を安全な方法で設定します。                 |
| CLIで意図せず既存Pageを更新しそう   | ディレクトリ内の`.jai-studio/page.json`、`--page-id`、対象のPage IDを確認します。初回用の新しい成果物ディレクトリを使うか、操作を中止して更新手順を確認します。 |
| URLから開けない、または想定外の人が開ける | 「アクセス設定」、アクセスモード、公開済みの版、共有先を確認します。URLの共有を広げる前に、管理担当者へ相談します。                                          |

問い合わせには、対象Project・Page名、SDK/CLI版、実行コマンドからキーを除いたもの、ZIPのファイル一覧、Page ID、発生日時、表示メッセージ、再現手順を記録します。APIキー、トークン、Cookie、Secret値、公開前のURLを添付しないでください。

## 次に読む記事

* [画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)
* [Pageのバージョンを管理する](/rupageskillrissu/manage-page-versions.md)
* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)
* [CLI Pages](/clirifarensu/cli-pages.md)
* [Pageのビルド・起動・更新](/gaidopage/page-build-start-update.md)
