疑難排解 Fabric 應用程式

在開發或部署 Fabric 應用程式專案時，診斷常見問題。本文涵蓋登入、本地服務、架構變更、靜態主機及 CLI 的問題。

部署問題

部署失敗時會發生 401 或 403 錯誤

症狀： 執行時 npx rayfin up 會回傳一個認證錯誤。

原因： 你的認證會話過期了，或者你沒有登入。

Solution:

重新驗證並重新嘗試部署：

npx rayfin login
npx rayfin up

靜態部署超出容量限制

症狀： 靜態內容部署會因大小限制錯誤而失敗。

原因： 壓縮檔案超過 100 MB。

Solution:

透過以下方式來減少建置輸出大小：

將原始碼地圖排除於生產編譯中
優化或移除大型影像與影片
將二進位檔案移到儲存裝置，而不是打包
驗證你的 bundler 設定可以排除開發出來的雜訊

靜態部署沒有遠端端點

症狀： 執行 npx rayfin up staticapp deploy 時，系統回報未設定遠端端點。

原因： 靜態部署是更新現有部署。它無法配置初始的遠端應用程式。

Solution:

執行一次完整部署：

npx rayfin up

佈建完成後，後續僅限靜態的更新請使用 npx rayfin up staticapp deploy。

驗證問題

認證令牌取得失敗

症狀：npx rayfin login 或是其他已認證的 CLI 指令報告 Failed to acquire authentication token 或憑證儲存錯誤。

原因： CLI 未登入，或環境未提供作業系統支援的憑證儲存。

Solution:

再次登入：

npx rayfin login

對於沒有憑證儲存的受限本地開發環境，你可以啟用加密備援：

npx rayfin login --encryption-fallback-enabled

Warning

加密後援機制會將權杖快取以明文方式儲存。只在可信賴的開發環境中使用它。不要在生產環境或共用環境中使用它。

症狀： 使用者在認證後立即登出。

原因： 客戶端沒有設定正確的基礎 URL 或可發佈金鑰。

Solution:

確認 RayfinClient 設定與你的後端相符：

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Symptom：瀏覽器在登入時會封鎖Fabric入口視窗。

原因：ensureSignedInWithFabric() 不是用戶手勢處理器呼叫的。

Solution:

從同步事件處理程序呼叫該函式：

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Fabric 驗證逾時

症狀： Fabric 驗證會在五分鐘後失敗。

原因：Fabric 傳送門在流量結束前沒有回傳交接代碼。

Solution:

確認這是否 returnOrigin 符合你應用程式的來源，關閉彈出視窗，然後重新開始登入流程。

Fabric SSO 報告來源不匹配

症狀： Fabric SSO 傳遞會拒絕該回應，因其來源不相符。

原因：returnOrigin、allowedRedirectUris或fabricPortalUrl與應用程式和 Fabric 入口網站運行的環境不符。

Solution:

將 returnOrigin 設為你應用程式的純來源。
確認 services.auth.allowedRedirectUris 中是否顯示來源。
請使用 Fabric 入口網站網址，以取得正確的生產、預覽或開發環境。
變更 npx rayfin up 後執行 rayfin.yml。

欲了解更多資訊，請參閱「配置認證重定向 URI」。

`initEmbeddedAuth()` 傳回 `null`

症狀： 內嵌認證不會建立會話。

原因：SDK 沒有偵測到該應用程式正在 Fabric 內部執行。

Solution:

請在應用程式 URL 中包含 ?fabricEmbedded=true ，或設定 fabricEmbedded: true 為 FabricAuthOptions。

Fabric 認證報告狀態不匹配

症狀： 登入失敗是因為回應狀態與請求狀態不符。

原因： 回應屬於過期流程或先前的登入嘗試。

Solution:

關閉 Fabric 彈出視窗並重新啟動登入流程。不要重複使用先前嘗試時的回調網址或狀態值。

資料模型問題

Data API 在部署後會回傳內部伺服器錯誤

症狀：npx rayfin up 或 npx rayfin up db apply 成功，但 GraphQL 或 REST 資料 API 會回傳內部伺服器錯誤。

原因：在 Microsoft SQL Server 中，沒有 max 的 @text() 欄位會產生 NVARCHAR(MAX) 資料行，這可能會導致無法產生 GraphQL 結構描述。

Solution:

為每個受影響的文字欄位新增明確的最大長度：

@text({ max: 200 })
title!: string;

接著檢視並套用結構變更：

npx rayfin up db apply --force

注意事項

使用 --force 前，請先檢查所有已回報的作業。這個選項可能會導致永久性的資料遺失。

資料服務需要方言

症狀： 部署失敗時出現 HTTP 400 回應並回報 Dialect is required when Data module is enabled。

原因：services.data.enabled 是 true，但 rayfin.yml 並不定義方言。

Solution:

配置 Microsoft SQL Server：

services:
  data:
    enabled: true
    dialect: mssql

部署後無法使用新實體。

症狀： 部署成功，但對新實體或變更實體的查詢失敗，或行為彷彿該實體不存在。

原因： 資料庫結構可能仍在運作，或前端使用過時產生的類型或快取設定。

Solution:

請檢查部署情況：
```
npx rayfin up status
```
等部署狀況良好再說。
更新或重建前端。
如果實體仍然失敗，則明確套用該結構：
```
npx rayfin up db apply
```

完整工作流程請參閱「套用並驗證結構變更」。

API 中未出現的關聯

症狀： 查詢時無法使用相關的實體欄位。

原因： 導航裝飾器缺失或架構未被套用。

Solution:

確認關聯裝飾器是否存在：

@one(() => Notebook) notebook?: Notebook;

重新套用結構。

授權政策無法運作

症狀： 使用者可以存取不該看到的紀錄。

原因： 保單表達錯誤或理賠名稱不符。

Solution:

請確認保單中理賠名稱正確（sub， email，）： role
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
記錄解碼後的 JWT，以確認理賠金額是否符合你的代碼。

過期的 API 回應

症狀： 前端在架構變更後會回傳過時的資料形狀。

原因： 產生的設定會被快取。

Solution:

停止後端服務。
刪除 .temp/ 中的 rayfin/ 目錄：
```
rm -rf rayfin/.temp/
```
重新啟動服務並重新套用結構。

CLI 問題

找不到命令

症狀： 執行中 npx rayfin 回傳「找不到指令」。

原因： CLI 沒有安裝，或者 npm 不在你的 PATH 裡。

Solution:

確認 Node.js 和 NPM 是否已安裝：
```
node --version
npm --version
```
重新安裝相依項目：
```
npm install
```

CLI 版本不匹配

症狀： CLI 指令在更新後會因意外錯誤而失敗。

原因： 快取的 CLI 版本已經過時。

Solution:

更新與重裝：

npm update --save
npm install
npx rayfin --version

CLI 全域與本地版本不匹配

症狀： CLI 指令在不同專案中會因意外錯誤而失敗。

原因： CLI 版本的全域和本地安裝都不一致。

解決方案：驗證本地版本 npm list @microsoft/rayfin-cli。這會顯示你目前使用的專案中 node_modules 的版本。請查看全球版本 npm list -g @microsoft/rayfin-cli。這顯示了系統全域安裝的版本。使用 npm uninstall -g 搭配 Rayfin CLI 套件來移除全域版本，並改用你的本機版本。

秘密管理問題

隱藏指令不會顯示提示訊息

症狀：npx rayfin secret set <NAME> 未提示輸入值就結束。

原因： 標準輸入不是互動終端機，或 CI 環境變數設定為 true。此指令使用遮罩式互動提示。

Solution:

請使用以下支援的非互動秘密創建替代方案之一：

透過將其值透過管線傳送給該指令來設定一個密鑰：
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```

從環境檔案設定多個秘密：

npx rayfin secret set --env-file .\secrets.env

不要讓機密值出現在你的 shell 歷史紀錄中，也不要將 secret.txt 或 .\secrets.env 提交到原始碼控制。

秘密指令回傳「權限遭拒」

症狀：npx rayfin secret set 或 npx rayfin secret list 回傳權限錯誤。

原因：應用程式尚未部署，或已登入的帳號無法存取目標的 Fabric 工作區。

Solution:

執行 npx rayfin up 以設定應用程式。
執行 npx rayfin login 並選擇一個有工作區存取權的帳號。
重試秘密指令。

欲了解更多資訊，請參閱管理函式秘密。

組裝與包裝問題

建置指令失敗

症狀： 靜態主機部署失敗，因為建置指令沒有產生任何輸出。

原因： 建置錯誤或建置指令錯誤。

Solution:

手動執行建置指令：
```
npm run build
```
修正任何報告的錯誤。
確認輸出資料夾裡有檔案。

空靜態資料夾

症狀： 靜態部署失敗時會出現「空資料夾」錯誤。

原因： 設定 folder 的路徑是錯誤的。

Solution:

確認 folder 路徑 rayfin.yml 與你的組裝輸出相符：

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

資料庫問題

資料庫架構 apply 失敗

症狀： 執行 npx rayfin up db apply 或 npx rayfin up db apply --force 時失敗。

原因：遠端資料庫的結構與應用程式程式碼中定義的架構不同步。應用程式程式碼是 Fabric 應用程式的真實來源。

不要透過 Fabric 入口網站、SQL Server Management Studio（SSMS）、Visual Studio Code 的 SQL Server 擴充功能或其他 SQL 工具修改遠端資料庫結構。以下資料實體欄位的變更不被支援：

重新命名欄位。
更改欄位的資料型態。
移除一根柱子。

支援新增欄位。移除或修改現有欄位可能會破壞應用程式及其在 Fabric 上的部署。

Solution:

將遠端資料庫架構的手動變更還原，使其與應用程式程式碼中的架構相符。
如果程式代理在應用程式程式碼中做出不支援的架構變更，請指示代理還原該變更。
再次執行 schema apply 指令：
```
npx rayfin up db apply
```
對於欄位重命名， --force 可能允許結構更新完成：
```
npx rayfin up db apply --force
```
注意事項

使用 --force 可能會導致永久性資料遺失。在進行前，請審查擬議的操作並確認您已接受資料遺失風險。

連線被拒

症狀： 資料操作會因連線錯誤而失敗。

原因： 資料庫容器無法執行，或是健康檢查失敗。

Solution:

檢視容器日誌：
```
docker compose logs -f
```
重新啟動服務。

重啟後資料遺失

症狀： 停止和啟動服務後資料會消失。

原因： 磁碟區是使用 --purge 刪除的。

Solution:

使用 --down 而不是 --purge 來保留資料。

已知的限制

關於目前的限制與建議的解決方法，請參見：

count() 在流暢的 GraphQL 用戶端上無法使用——請使用 results.length。
多對多關係不受支援——請使用明確定義的聯結實體。
會話物件是不透明的——檢查 isAuthenticated 或 user 屬性。
在 rayfin.yml 中啟用或停用驗證後，請重新啟動後端。

尋求幫助

如果問題仍然存在：

請參考 Fabric Apps 文件。
請查看 GitHub 倉庫是否有已知問題。
提交包含詳細日誌和重現步驟的錯誤報告。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-29

疑難排解 Fabric 應用程式

部署問題

部署失敗時會發生 401 或 403 錯誤

靜態部署超出容量限制

靜態部署沒有遠端端點

驗證問題

認證令牌取得失敗

登入後會話未持續存在

Fabric SSO 彈出視窗被封鎖

Fabric 驗證逾時

Fabric SSO 報告來源不匹配

initEmbeddedAuth() 傳回 null

Fabric 認證報告狀態不匹配

資料模型問題

Data API 在部署後會回傳內部伺服器錯誤

資料服務需要方言

部署後無法使用新實體。

API 中未出現的關聯

授權政策無法運作

過期的 API 回應

CLI 問題

找不到命令

CLI 版本不匹配

CLI 全域與本地版本不匹配

秘密管理問題

隱藏指令不會顯示提示訊息

秘密指令回傳「權限遭拒」

組裝與包裝問題

建置指令失敗

空靜態資料夾

資料庫問題

資料庫架構 apply 失敗

連線被拒

重啟後資料遺失

已知的限制

尋求幫助

相關內容

意見反應

其他資源

`initEmbeddedAuth()` 傳回 `null`