共用方式為

詳細設定指南

一旦你按照入門指南獲取程式碼（無論是在 Codespaces 還是本地），請按照下列步驟進行操作：

小提示

如果你不想手動操作，可以請 GitHub Copilot 幫忙完成這些工作。 Starter-Kit 資料庫具備 AI 支援，Copilot 可以互動式引導你完成設定流程。 試試這個提示：「 幫我開始使用這個倉庫並執行 HelloWorld 範例。」

步驟 1：執行設定腳本

安裝腳本可自動執行大部分設定 （應用程式註冊、預設值等） 。

# From the repo root
pwsh ./scripts/Setup/Setup.ps1 -WorkloadName "Org.MyWorkload"

設定腳本說明：

  • WorkloadName 必須遵循型樣 Organization.WorkloadName。 開發時請使用 Org.[YourWorkloadName]。
  • 如果重複使用現有的 Microsoft Entra 應用程式，請確保根據存放庫的手動設定指南所述，已正確設定 SPA 重新導向 URI。
  • 在 macOS/Linux 上，用於 pwsh 執行指令碼。
  • 請確定 PowerShell 執行原則已設定為 [不受限制]，而且如果系統詢問您是否應該啟動 PowerShell 檔案，檔案會解除封鎖。
  • 請遵循指令碼提供的指引來設定所有內容

安裝程式指令碼可以執行數次。 如果值已經存在，系統會詢問您是否應該覆寫它們。 如果您想要覆蓋所有內容，請使用 Force 參數。

備註

如果你遇到設定錯誤，請參考下方故障排除區塊的 PowerShell 設定錯誤 。

小提示

如果你在自動設定腳本上遇到問題，可以依照手動 設定指南 逐步手動設定。

步驟 2：啟動開發環境

執行開發伺服器 （前端 + API），並透過 DevGateway 向 Fabric 註冊本機執行個體。

# Terminal 1: start local dev server
pwsh ./scripts/Run/StartDevServer.ps1

# Terminal 2: start DevGateway to register your local instance with Fabric
pwsh ./scripts/Run/StartDevGateway.ps1

步驟 3：在 Fabric 中啟用開發者功能

前往 Fabric 入口並設定所需設定：

3.1 在管理入口網站設定租戶設定：

前往管理入口網站設定並啟用下列租用戶設定：

  • 容量管理員和參與者可以新增和移除額外的工作負載
  • 工作區管理員可以開發合作夥伴工作負載
  • 使用者可以查看並使用未經 Microsoft 驗證的其他工作負載

租用戶設定的螢幕擷取畫面。

3.2 開啟 Fabric 開發者模式：

進入 Fabric 開發者設定並啟用 Fabric 開發者模式：

Fabric 開發者模式的截圖。

你現在準備好用布料製作你的第一個 Hello World 商品了。

步驟四：測試 HelloWorld 項目

您可以從工作負載集線器存取您的工作負載（尋找您的工作負載名稱）或直接瀏覽。 然後建立 Hello World 項目。

Steps:

  1. Open Fabric 工作負載中心：定位你的工作負載（例如）。 Org.MyWorkload

    • 直接導航： https://app.fabric.microsoft.com/workloadhub/detail/<WORKLOAD_NAME>?experience=fabric-developer
    • 請用你的實際工作負載名稱替換 <WORKLOAD_NAME> （例如， Org.MyWorkload）

  2. 建立新項目：選擇 Hello World 項目類型並選擇你的開發工作區。

  3. 驗證功能：編輯器開啟;確認該物品正常運作，且在工作區中顯示為原生的產物。

祝賀！ 你從開發環境中創造了第一個項目。

步驟五：開始編碼

現在你已經準備好了，可以開始創作自己的客製化物品了。 請參考我們的全面指南，學習如何製作客製化布料商品：

📖 製作客製化布料物品指南 - 本指南提供兩種製作方法：

  • AI-Assisted 方法論：使用 GitHub Copilot 進行互動式指導（建議新手開發者）
  • 手動腳本化方法：使用自動化的 PowerShell 腳本快速設定（建議有經驗的開發者）

快速入門選項：

  • 更新現有的 HelloWorld 編輯器： Workload/app/items/HelloWorldItem/HelloWorldItemEditor.tsx
  • 或使用腳本搭建新項目： ./scripts/Setup/CreateNewItem.ps1

快樂編碼！ 🚀

最佳做法

  • 分支倉庫：分支 Starter-Kit 倉庫，並以你的分支作為專案的基礎。
  • 保持同步：保持您的分支與上游同步，以獲取改進。
  • 維持專案結構一致性：保留入門套件的專案結構與組織模式，以確保與未來更新相容並維持程式碼清晰度。
  • 定期整合 Starter-Kit：定期將 Starter-Kit 的程式碼變更整合進專案，以獲得錯誤修正、新功能及安全更新。 建立一個流程，定期（每月或每季）審查並合併上游變更。
  • 及早驗證工作清單：及早驗證你的工作量清單，並遵守最低權限權限。
  • 使用開發容器：使用開發容器或 Codespaces，營造一致且可拋棄的環境。
  • 使用提供的腳本：使用提供的腳本（Setup、StartDevServer、StartDevGateway）來自動化設定與日常工作流程。

疑難排解常見問題

PowerShell 設定錯誤

如果在執行設定腳本時遇到錯誤，請確保你在執行腳本的環境中安裝並設定了最新的 PowerShell。

PowerShell 安裝錯誤的螢幕擷取畫面。

腳本執行政策錯誤

如果你遇到： cannot be loaded because the execution policy is unrestricted

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

5173號埠正在使用中

如果 DevServer 無法在 5173 埠啟動，請找出並終止該程序：

# Find process using port
Get-Process -Id (Get-NetTCPConnection -LocalPort 5173).OwningProcess

# Terminate process
Stop-Process -Id <ProcessId> -Force

相依性錯誤

如果你遇到缺少相依關係的錯誤：

# From Workload folder
cd Workload
npm install

DevGateway 認證問題

如果啟動 DevGateway 時驗證失敗：

  1. 在 Microsoft Entra 中驗證應用程式註冊的重定向 URI
  2. 檢查租戶設定是否允許開發者所需的功能
  3. 請確認你在 DevGateway 上登入的租戶是正確的

如需完整的故障排除資訊，請參閱 Starter-Kit 儲存庫 README。

重要注意事項

新的 Chrome 本地網路存取限制

Google 在 Chrome 中引入了新的區域網路存取（LNA）限制，這將破壞與 DevServer 的本地開發。 這些限制防止網站在未經明確使用者許可下存取本地網路資源。

本地開發所需行動：您必須更改 Chrome 設定以繼續在本地開發工作負載：

  1. 在 Chrome 中導航到chrome://flags/#local-network-access-check
  2. 將旗標設為「停用」
  3. 重新啟動 Chrome

為什麼需要這樣做：新的限制阻擋了你在 Fabric 中運行的工作負載與本地 DevGateway 伺服器之間的通訊，而這對開發工作流程至關重要。

其他資源：

這很重要

若不禁用此標識，使用 DevGateway 的本地開發將無法在 Chrome 上運行。 此配置變更僅適用於開發環境。

後續步驟

  • Last updated on