> 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/page-source-structure-and-runtime.md).

# Pageのソース構成とランタイム

Pageを配信する開発者は、ローカルで生成したブラウザ向けの成果物をZIPにまとめます。Studioへの登録処理は、受け取ったZIPを検査してファイルを配信対象として配置するものです。アップロード時に依存関係をインストールしたり、`package.json` のスクリプトを実行したりする処理は確認できません。

したがって、リポジトリのソース一式ではなく、利用者のブラウザで読み込める完成済みのHTML、JavaScript、CSS、画像などを準備してください。登録・公開の画面操作は[画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)、容量・ZIP構造などの制限は[Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)を正本として確認します。

## 関連記事

* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)
* [Pageをローカル確認してデプロイする](/gaidopage/local-preview-and-deploy-page.md)
* [画面からPageを登録・公開する](/rupageskillrissu/register-and-publish-pages.md)

## この記事の範囲

この記事では、ZIPに入れる配信対象、登録時に除外される内容、確認できるランタイムの扱いを説明します。React、Vue、Next.jsなどの特定フレームワークの採用、Node.jsなどのサーバーランタイム、サーバーサイドレンダリング、APIルート、任意のビルドコマンドの対応可否は、この確認範囲では確定できません。

Pageの配信先は、Studio本体とは別のPage用ホストとして参照され、Studioではiframeで表示されます。ただし、Page用ホスト側がどのURLを起点ファイルへ対応付けるか、SPAの深いURLをどのように処理するか、サーバー処理を実行できるかは、確認したソースだけでは判断できません。未確認の挙動を前提にルーティングやバックエンドを構成しないでください。

## 始める前に

* 対象Project、Page名、利用者が最初に開く画面、想定するブラウザを確認します。
* ローカルでビルドを完了し、生成された成果物だけを別のフォルダーへ集めます。元のソース、依存関係、開発用設定をそのままZIPにしないでください。
* 最初に読み込むHTMLと、そのHTMLが参照するJavaScript、CSS、画像、フォントなどが、成果物内の相対パスでそろっていることを確認します。
* ブラウザへ届くファイルには、パスワード、APIキー、トークン、Project Secretの値、個人情報を含めないようにします。Secretの管理は[Project Secretを登録・更新・削除する](/guan-li-yun-yong/manage-project-secrets.md)を参照してください。

> `package.json`、ロックファイル、ソースマップ、環境変数ファイルを、登録時のビルドのために含める必要はありません。秘密値を含み得るファイルを成果物へ混在させないでください。

## 配信対象として準備する構成

登録処理は、ZIP内の通常ファイルを読み取り、許可されたパスをそのまま配信対象へ配置します。HTMLファイル名、エントリーポイント名、`package.json` の有無、`scripts` の名前を検証する処理は確認できません。`index.html` を必須とする検証も、この範囲では確認できません。

このため、次のように「ビルド後にブラウザへ配るファイル」をZIPのルートに置く構成を基本にします。ファイル名は例であり、Studioがこの構成やフレームワークを指定するものではありません。

```
page-release.zip
├── index.html
├── assets/
│   ├── app-xxxxx.js
│   └── app-xxxxx.css
└── images/
    └── logo.svg
```

HTMLから参照するパスは、ZIP展開後の配置を基準に解決できる必要があります。開発サーバー固有の変換、プロキシ、環境変数、履歴APIフォールバックに依存する場合は、ビルド済み成果物で先に検証してください。

### `package.json` とビルドスクリプトの扱い

`package.json` を含めても、登録時に `npm run build`、`pnpm build`、`yarn build` などが実行される根拠は確認できません。また、依存関係を復元する処理、フレームワーク名から出力先を検出する処理、出力フォルダーを自動選択する処理も確認できません。

そのため、開発時には使用するツールチェーンでビルドし、ZIPには**その出力内容をルートへ展開した状態**で入れます。たとえばローカルの `dist` や `build` をZIPの親フォルダーにしただけでは、そのフォルダー名が登録時に除外され、成果物が配信されない可能性があります。

> 特定フレームワークやサーバー出力の実行可否は確認できません。最終的にブラウザ向けの成果物を生成できるかで判断してください。

## 登録時に除外されるフォルダーとファイル

`__MACOSX`、`node_modules`、`.git`、`.DS_Store`、`.jai-studio`、`__staging`、`__upload-lock.json`、`__backup`、`__versions`を含むパスと、ルートの一般的なビルド出力用フォルダーは除外されます。詳細は[Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)を正本として確認してください。

単一の親フォルダーだけで全ファイルを包んだZIPでは、その親フォルダーは取り除かれます。親フォルダー直下のビルド出力用フォルダーも除外されるため、次のようなZIPは適しません。

```
page-release.zip
└── my-app/
    └── dist/
        └── index.html
```

成果物を抽出して、HTMLとアセットをルートへ置くように作り直してください。ZIP内に現在ディレクトリまたは親ディレクトリを表すパス要素がある場合は、構造エラーになります。除外後に配信対象ファイルが残らないZIPも登録できません。

## ランタイムでの表示

登録処理は、ZIPを展開してファイルを配置します。Pageを更新すると、新しい成果物に含まれない以前のファイルは配信対象に残りません。バージョン操作は[Pageのバージョンを管理する](/rupageskillrissu/manage-page-versions.md)を参照してください。

Studio内でPageを開く場合、StudioはPage用ホストのURLを作成し、認証が必要なPageでは短期の認証情報を付与したURLをiframeの表示先に設定します。外部顧客認証を使うPageでは、同じ方法で認証情報を付与しない経路があります。どのアクセス設定でも、配信ファイルがブラウザへ届くことを前提に、秘密値をクライアント用のコードや設定へ埋め込まないでください。

ランタイムは、登録されたソースを改めてコンパイルするものとしては確認できません。JavaScriptは利用者のブラウザで実行されます。サーバー側の処理、秘密値の安全な参照、利用可能な環境変数はこの構成だけでは確定できないため、[Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)を確認してから実装します。

## よくある誤解

### ZIPに開発プロジェクト全体を入れればよい

登録処理はプロジェクトをインストール・ビルドするものではありません。`node_modules` は除外され、ルートの一般的な出力フォルダーも除外されます。HTMLとアセットを含む完成済みの配信物だけを入れます。

### `index.html` があれば必ず表示できる

登録時に `index.html` の存在を検証する処理は確認できません。また、Page用ホストが任意のURLをどのファイルへ解決するかも、この範囲では確定できません。HTML、参照先アセット、相対パスをそろえたうえで、実際に登録したPageを開いて確認してください。

### クライアント側の設定ならSecretを入れてもよい

ブラウザへ配信された値は、利用者やブラウザの開発者ツールから取得され得ます。難読化、変数名の変更、非表示の画面要素は保護になりません。秘密値を配布ファイル、ソースマップ、初期データ、ログへ入れないでください。

## うまくいかない場合

| 状況                       | 確認・対応                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| 登録後に必要なファイルが見つからない       | ZIPを展開して、HTMLとアセットがZIPのルートにあるか、除外対象のフォルダー名の下に置いていないかを確認します。                                                               |
| ローカルでは表示できるがPageでは表示できない | 開発サーバー固有のプロキシ、書き換え、環境変数、履歴APIフォールバックに依存していないかを確認します。ブラウザのネットワーク表示で、失敗したファイルのURLとContent-Typeを確認します。                       |
| 更新後に古い画面やアセットが表示される      | 新しいZIPに必要なHTML・JavaScript・CSSがすべて含まれるかを確認し、適用中のバージョンと実際のPage表示を確認します。                                                     |
| ZIPの構造エラーになる             | パスに現在・親ディレクトリを表す要素がないか、除外後に配信対象の通常ファイルが残るかを確認します。上限・構造条件は[Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)を参照します。 |
| サーバーコードやSecretを使いたい      | クライアント側に代替実装を置かず、対応するランタイムと安全な参照方法を[Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)で確認します。          |

問い合わせるときは、対象ProjectとPage名、ZIP内のファイル一覧、発生日時、表示されたメッセージ、ブラウザの失敗したリクエスト、再現手順を共有します。ZIP、ログ、スクリーンショットにはSecret、APIキー、トークン、個人情報を含めないでください。

## チェックリスト

* [ ] ローカルでビルドを完了し、ブラウザ向けの成果物だけを取り出した
* [ ] 最初に表示するHTMLと、参照されるアセットのパスを確認した
* [ ] `package.json` のスクリプト実行や依存関係インストールを前提にしていない
* [ ] 除外対象のフォルダー名の下に、配信に必要なファイルを置いていない
* [ ] ZIPを展開して、不要な親フォルダーや親ディレクトリへのパスがないことを確認した
* [ ] ブラウザへ届くファイルに秘密値や個人情報が含まれていない
* [ ] 登録後に実際のPageを開き、代表的な表示と操作を確認する準備ができている

## 次に読む記事

* [Pageをローカル確認してデプロイする](/gaidopage/local-preview-and-deploy-page.md)
* [Pageの仕様・制限](/shi-yang-zhi-xian/page-specs-and-limits.md)
* [Pageのサーバー処理・環境変数・Secret参照](/gaidopage/page-server-env-and-secrets.md)
