# JSON 檔案格式

> 💡 **提示**：根據使用情境，可以只包含部分欄位。詳見 [上傳資料](/pagespeed/02-upload-data.md) 的三種情境說明。

## 完整格式規格

```json
{
  "credentials": {
    "api_key": "你的 Google PageSpeed API Key"
  },
  "share_report": {
    "upload": false,
    "r2": {
      "accountId": "YOUR_CLOUDFLARE_ACCOUNT_ID",
      "accessKeyId": "YOUR_R2_ACCESS_KEY_ID",
      "secretAccessKey": "YOUR_R2_SECRET_ACCESS_KEY",
      "bucketName": "YOUR_R2_BUCKET_NAME",
      "autoDelete": true,
      "deleteDays": 7,
      "shareExpireDays": 7
    }
  },
  "urls": [
    "https://example.com",
    "https://example.com/page2"
  ],
  "reports": {
    "https://example.com": {
      "mobile": { /* PageSpeed 報告資料 */ },
      "desktop": { /* PageSpeed 報告資料 */ }
    }
  }
}
```

## 最小格式範例

### 只啟用 Pro Mode（不清空資料）

```json
{
  "credentials": {
    "api_key": "YOUR_API_KEY"
  }
}
```

### 只匯入網址（基本模式）

```json
{
  "urls": [
    "https://example.com"
  ]
}
```

## 欄位說明

### credentials

* `api_key`: 選填，填入後會自動啟用 Pro Mode

### share\_report

* 選填，用於分享報告功能
* 不需要分享功能可省略此區塊

#### share\_report.upload

* `true`: 啟用上傳功能，分析後自動上傳報告到你的 R2
* `false`: 停用上傳功能，即使填寫了 r2 設定也不會上傳

#### share\_report.r2

* 選填，你的 Cloudflare R2 儲存空間設定
* 只有當 `upload: true` 時才會使用
* `accountId`: Cloudflare Account ID
* `accessKeyId`: R2 API Token 的 Access Key ID
* `secretAccessKey`: R2 API Token 的 Secret Access Key
* `bucketName`: R2 Bucket 名稱
* `autoDelete`: 是否自動刪除過期報告（預設 true）
* `deleteDays`: 報告保留天數（預設 7 天）
* `shareExpireDays`: 分享連結有效天數（預設 7 天）

#### ⚠️ 重要：R2 Bucket 必須設定 CORS

使用自己的 R2 儲存時，**必須**在 R2 Bucket 設定 CORS Policy，否則瀏覽器會阻擋連線。

**設定步驟**：

1. 前往 Cloudflare Dashboard 的 R2 Bucket 設定頁面：

   ```
   https://dash.cloudflare.com/[你的 Account ID]/r2/buckets/[Bucket 名稱]/settings
   ```
2. 找到「**CORS Policy**」區塊，點擊「**Edit**」
3. 貼上以下 JSON 設定：

```json
[
  {
    "AllowedOrigins": ["*"],
    "AllowedMethods": ["GET", "PUT", "DELETE", "HEAD"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]
```

4. 點擊「**Save**」儲存設定

**CORS 設定說明**：

* `AllowedOrigins: ["*"]`：允許所有來源存取（生產環境建議改為特定網域，如 `["https://yourdomain.com"]`）
* `AllowedMethods`：允許的 HTTP 方法（GET、PUT、DELETE、HEAD）
* `AllowedHeaders: ["*"]`：允許所有請求標頭
* `ExposeHeaders: ["ETag"]`：允許瀏覽器讀取 ETag 標頭
* `MaxAgeSeconds: 3000`：預檢請求（preflight）的快取時間（50 分鐘）

**如果沒有設定 CORS**，匯入 JSON 時會出現：

```
Pro Mode
您上傳的設定檔中，R2 連線資訊有問題（NetworkError when attempting to fetch resource.）。
分享功能暫時無法使用，但網站分析功能不受影響唷！
```

### urls

* **必填**（除非只上傳憑證）
* 要分析的網址清單
* 上傳時會清空現有資料並載入新網址

### reports

* 選填，已經分析過的報告
* 包含手機版和桌面版的分析結果
* 格式：`{ "url": { "mobile": {...}, "desktop": {...} } }`

***

## 範例檔案

完整的範例 JSON 檔案位於專案中：

```
/url-templates/example-urls.json
```

線上檢視：[example-urls.json](https://pagespeed.lazypro.app/url-templates/example-urls.json)

此範例包含完整的欄位結構，可作為建立自己的設定檔時的參考。

***

## 使用建議

1. **首次使用**：上傳完整格式（含 `urls`）
2. **分享後繼續分析**：只上傳 `credentials`（不清空資料）
3. **切換專案**：上傳新的完整格式（會清空舊資料）
4. **匯出分享**：使用 Download 按鈕（不含憑證，安全分享）

詳細說明請參閱：[上傳資料](/pagespeed/02-upload-data.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lazypro.app/pagespeed/03-json-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.