Fabric 應用程式的靜態內容託管

Fabric Apps 包含靜態內容託管服務，能建置、打包並服務你的前端應用程式與後端 API。啟用靜態主機時，CLI 會將你建置的資產部署到 Fabric，並提供主機網址。你可以要求使用者登入並取得查看 Fabric 應用程式的權限，或者允許匿名存取託管資產。

先決條件

一個包含前端應用程式（例如 React、Vue 或純版 TypeScript）的 Fabric Apps 專案。
一個產生靜態輸出的建置指令（例如 npm run build）。

靜態主機運作方式

當你啟用靜態主機時，CLI 會執行以下步驟：

執行你設定好的建置指令（例如， npm run build），。
驗證輸出資料夾是否存在且包含檔案。
將所有檔案打包成壓縮的 ZIP 壓縮檔（最大 100 MB）。
將壓縮檔上傳至 Fabric Apps 主機。
套用已設定的存取設定並回傳一個主機網址。

設定靜態主機

在你的staticHosting檔案中，於services下方新增一個rayfin/rayfin.yml區塊：

services:
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html
    assetAccess: protected

設定選項

選項	Required	預設值	Description
`enabled`	是的	—	設定為 `true` 以啟用靜態託管。
`folder`	是的	—	輸出資料夾包含相對於 `root`的建置靜態檔案。
`root`	No	專案根目錄	前端專案的根目錄，相對於專案根目錄。
`buildCommand`	No	—	在打包前執行 Shell 指令（例如， `npm run build`）。
`indexDocument`	No	—	用來回應目錄請求的預設文件（例如 `index.html`）。
`assetAccess`	No	`protected` 用於非互動式部署	控制對託管資產的存取。使用`protected`來要求登入並允許查看 Fabric 應用程式，或`public`允許匿名存取。

設定對託管資產的存取權限

設定 assetAccess 為以下其中一個值：

protected- 要求使用者登入並擁有權限才能瀏覽 Fabric 應用程式，才能取得託管資產。
public - 允許任何擁有主機網址的人在不登入的情況下取得託管資產。

受保護的託管會控制對 Fabric Apps 提供之靜態檔案的存取。它不會取代你應用程式或 API 中的認證與授權。

第一個互動 npx rayfin up 式部署會提示你選擇存取設定（如果 assetAccess 尚未設定）。非互動式部署會使用 protected 並將該設定儲存為 rayfin.yml。

部署後若要更改存取設定，請更新 assetAccess，然後執行完整部署：

npx rayfin up

指令只更新 npx rayfin up staticapp deploy 內容。它不會套用新的 assetAccess 數值。

有獨立前端目錄的範例

如果你的前端程式碼存在子目錄：

services:
  staticHosting:
    enabled: true
    root: frontend
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html
    assetAccess: protected

此配置將輸出路徑解析為 <project-root>/frontend/dist。

部署靜態內容

全面部署

當你執行 npx rayfin up時，靜態內容會自動部署，作為全端部署的一部分：

npx rayfin up

CLI 會建置你的前端，打包輸出，並與後端配置一起上傳。部署後，CLI 會列印主機 URL，並將其寫入你的.env.fabric-*檔案。VITE_RAYFIN_HOSTING_URL

獨立靜態部署

使用 staticapp deploy 這個子指令，只重新部署你的靜態內容，而不重執行整個部署：

npx rayfin up staticapp deploy

這個指令很適合只修改前端程式碼，想要更快的迭代週期。

跳過建置步驟

如果你已經建置好前端，想部署現有輸出而不重建：

npx rayfin up staticapp deploy --skip-build

啟用詳細日誌記錄

在部署期間顯示詳細輸出：

npx rayfin up staticapp deploy --verbose

認證回撥設定

當同時啟用靜態主機與認證時，Rayfin CLI 會根據你的主機 URL 自動註冊一個認證回調 URI。

例如，如果你的主機 URL 是 https://example.webapp.com，CLI 會新增這個回調 URI：

services:
  auth:
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
      - https://example.webapp.com/auth/callback

你不需要手動設定驗證回調 URI——CLI 會在部署時更新設定並推送。

部署規模限制

壓縮後的 ZIP 壓縮檔不得超過 100 MB。
CLI 採用最大壓縮來最小化上傳大小。
如果你的建造產出超過限制，請透過以下方式優化你的資產：
- 從正式環境建置中排除來源映射檔。
- 壓縮或移除大型影像與影片。
- 將二進位檔案移到 Fabric Apps 儲存，而不是將它們打包。

完整範例

完整 rayfin.yml 配置，啟用靜態主機、認證及資料服務：

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    fabric:
      enabled: true
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html
    assetAccess: protected

本地測試

部署前，請確認你的靜態建置在本地運作：

打造你的前端：
```
npm run build
```
檢查輸出資料夾是否包含預期的檔案：
```
ls dist
```
將建置檔案提供給本地靜態伺服器：
```
npx serve dist
```
打開伺服器列印的網址，確認你的應用程式是否正確載入。

為部署問題進行疑難排解

找不到靜態資料夾

如果 CLI 回報靜態資料夾不存在：

確認 folder 中的 rayfin.yml 路徑是否正確，且是相對於 root 的路徑（如果未設定 root，則相對於專案根目錄）。
確保你的建置指令成功執行，並在預期的目錄中產生輸出。

空靜態資料夾

輸出資料夾空通常代表建置指令失敗或沒有產生輸出。手動執行建置指令檢查錯誤：

npm run build

部署超過容量限制

如果 ZIP 超過 100 MB：

檢查你的建置輸出是否有不必要的檔案（來源地圖、開發資產）。
將打包工具設為在正式環境建置中排除原始碼對應檔。
將大型二進位檔案移到 Fabric Apps 儲存。

沒有設定遠端端點

該 npx rayfin up staticapp deploy 指令需有現有的遠端部署。先執行 npx rayfin up 以設定遠端端點，然後在後續更新時使用 staticapp deploy。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-29