react-app

適用：使用者已經有一個 React、Vite（或 Vue、Svelte 這類）專案，平常用 npm run build 產生 dist/（Create React App 是 build/），

現在要放到醫智匯給院內同仁用；或使用者明確想用 React 開發。只是一兩個網頁的小工具不用這份，用 static-app 或 form-app 比較快。

平台怎麼對待這種專案（M48，2026-10-13）：原始碼和建置輸出都存進平台（都經過安全檢查，接手的人改得了），

app-manifest.yml 用 site_dir 指出哪個資料夾是網站，發佈時只放那個資料夾。建置在使用者的電腦上做，平台不替你跑 npm。

做法

• 分級問診、建立應用：照平台工具做（wanfangai_classify、wanfangai_create_app）。

建立後平台回的起始檔案裡，只把 `app-manifest.yml` 寫進使用者原本的專案資料夾根目錄；範本的 index.html 不要蓋掉他自己的。

• 宣告檔：在 app-manifest.yml 加一行 site_dir: dist（Create React App 寫 build）；skills_used 加 react-app；

要存資料的，data.collects 照實寫（見第 6 步）。分級那幾欄是平台寫的，不要改。

• 網址與路由：應用掛在自己的網址根目錄（https://<代號>.apps.…/），Vite 的 base 維持預設 / 就好，不要改成相對路徑以外的子路徑。

React Router 的 BrowserRouter 可以用：平台找不到的路徑會回 index.html。

• 東西只能從應用自己或平台載入：所有套件、圖片都要打包進 `dist/`（import 進來，或放在 public/），

不要在 index.html 引用外部 CDN、Google Fonts——上線後安全設定會擋。平台有提供的函式庫可以從平台載入（契約 §4.9）。

搬別人做好的專案時，第一件事就是檢查：在專案裡找 http://、https://（index.html、src/、CSS 的 @import 與 url(），

常見的是 fonts.googleapis.com、fonts.gstatic.com、cdn.jsdelivr.net、unpkg.com。找到的就拿掉，告訴使用者你改了什麼、為什麼。

2026-10-13 實跑：Google Fonts 的連結原樣上線、被擋，沒人告訴使用者。

• 字型：換成平台書架上的同一套，不要退回系統字型。拿掉 Google Fonts 之後，在 `index.html` 的 `<head>` 加平台的那一行，

CSS 的 font-family 不用改（還是 'Noto Sans TC'、'Noto Serif TC'）。只會下載頁面用到的字。

| 原本連 Google Fonts 的 | 在 index.html 的 <head> 加（用到哪個字重放哪一行） |

|---|---|

| Noto Sans TC（400／500／700） | <link rel="stylesheet" href="https://platform.wanfangai.tw/lib/noto-sans-tc@5.3.1/400.css">（500.css、700.css 同一個資料夾） |

| Noto Serif TC（400／700） | <link rel="stylesheet" href="https://platform.wanfangai.tw/lib/noto-serif-tc@5.3.1/400.css">（700.css 同一個資料夾） |

| 其他字型（Inter、Roboto、思源以外的中文字型…） | 書架沒有：才改用系統字型（font-family: system-ui, "Microsoft JhengHei", "PingFang TC", sans-serif），並告訴使用者 |

跟使用者說：「醫院平台不准網頁從外部網站載入東西，所以改用平台提供的同一套字型，畫面一樣。」版本以 https://platform.wanfangai.tw/lib/index.json 為準。

做完確認：發佈後打開試用版，按 F12 的「網路（Network）」看得到 /lib/noto-sans-tc@… 的請求。CSS 寫了 'Noto Sans TC' 卻沒有這一行，畫面會是系統字型——

2026-10-14 實跑就是這樣（讀了對照表，還是退回系統字型）。

• 登入與存資料用平台的，不要自己做登入、不要接外部資料庫：
• 在 index.html（Vite 是專案根目錄那份）的 <head> 加 <script src="https://platform.wanfangai.tw/sdk/v1.js"></script>，放在打包後的程式之前。
• React 裡用 window.UberTeach：useEffect(() => { UberTeach.me().then(setMe); }, [])；存資料 UberTeach.data.save()、查 list()、改 update()。

細節照 form-app 做法（wanfangai_read_skill，name: form-app）。TypeScript 專案宣告一下 declare const UberTeach: any; 或寫一個小型別。

• 不要放機密：.env、.env.* 會被打包程式擋下（平台不收放密碼的檔案）。VITE_ 開頭的設定會被編進網頁、任何人看得到，只能放公開的值。
• 建置：在專案資料夾執行 npm install（第一次）與 npm run build。下載套件要連網路，沙箱擋住時用要求提高權限的方式執行。

每次改完、存版本之前都要重新建置——發佈的是 dist/，忘了建置等於發佈舊版。

• 存版本：用打包上傳（檔案多、有建置輸出）：wanfangai_upload_url 拿網址，在專案資料夾執行外掛附的

pack-upload.cjs <網址>（wanfangai-publish 那份 skill 的 scripts/），再呼叫 wanfangai_save_version 帶 upload_id。

node_modules、.git 不會打包；src/、dist/、package.json、package-lock.json 都會存。

• 發佈：照平台工具（wanfangai_publish）。安全檢查會掃原始碼和 dist/；dist/ 裡被擋的東西，多半要回原始碼修好再建置一次。
• 說「做好了」之前：打開試用版，看瀏覽器主控台有沒有紅字（被安全設定擋的東西會出現在那裡），每個功能點一次。

確認不了的不要說它已經可以用，改成請使用者打開確認哪幾項。

從零開始（還沒有專案）

• 先看這台電腦能不能做：執行 node -v。要 20.19 以上——最新的 Vite 在 Node 18 上一啟動就出錯（does not provide an export named 'styleText'，2026-10-15 實測），

Vite 本身也要 20.19 以上。版本不夠、或 npm 下載不了套件（院內電腦常擋外網），不要一直重試，用一句話讓使用者選：

(a) 改在能連網、能裝 Node 22 的電腦（例如家裡）做，平台工具一樣能存版本，回到院內電腦再讀回來（wanfangai_read_files）；

(b) 不用 React：改成單頁工具（static-app、form-app），要比較多互動就用書架的 alpinejs-csp，什麼都不用安裝。

• 建立專案：在要放專案的地方執行 npm create vite@latest <網址代號> -- --template react（要 TypeScript 用 react-ts；要連網路，用提高權限的方式執行）。

不是在終端機互動時它不會問問題，直接建好資料夾。接著在那個資料夾 npm install。

• 分級問診、建立應用，平台回的起始檔案只取 `app-manifest.yml` 與 `.wanfangai-version` 寫進 Vite 專案的最上層（範本的 index.html 不要蓋掉 Vite 的）。
• 把範本的示範內容換掉：src/App.jsx 裡有連到 vite.dev、react.dev、GitHub、X 的連結和 Vite 的圖，換成使用者要的畫面。

2026-10-15 實測：範本建置出來的 dist/ 過得了平台的安全檢查（只有「圖片沒掃描」的提醒）。

• 接著照上面「做法」第 2 步以後做（site_dir: dist、字型、身分 SDK、建置、打包上傳、發佈）。

把已上架的單頁工具改寫成 React

使用者已經有一個在平台上的應用（單一 index.html 那種），想改用 React 重寫：

• 同一個應用、同一個網址，不要建新的應用：先 wanfangai_read_files 把現在的檔案讀回來（含 .wanfangai-version），在那個資料夾裡建 React 專案

（npm create vite@latest 建在旁邊的暫存資料夾，再把 package.json、vite.config.js、src/、index.html 搬進來；舊的 index.html 改名留著對照，完成後刪掉）。

• app-manifest.yml 加 site_dir: dist、skills_used 加 react-app。不用重新分級——分級那幾欄（等級、開放程度、存什麼資料、外部連線）沒變就不用；用途或存的資料變了才要（wanfangai_classify）。
• 有存資料的：集合名稱、欄位名稱維持原樣（UberTeach.data.save({ collection: '…' }) 的那個名字），新版才讀得到舊資料。改名等於從空的開始。
• 先發試用版，請使用者確認：舊資料都看得到、每個功能都還在，再發正式區。網址不變，同仁不用換書籤。
• 改寫期間舊版照常在線上；有人同時在用舊版存資料也沒關係，資料存在平台，不在程式裡。

常見問題

• 畫面空白：打開瀏覽器的開發者工具看 Console。常見原因是引用了外部 CDN（被安全設定擋）、或 base 改成了別的路徑。
• 存版本說 `site_dir` 的資料夾不存在：忘了建置，或 site_dir 寫錯（Vite 是 dist、CRA 是 build）。
• 打包後超過 50 MB：多半是把影片、備份或 node_modules 以外的大資料夾放在專案裡；大型媒體先壓縮。
• 想讓平台替你建置（只存原始碼）：目前不支援（平台的 CI 不會下載外部套件來執行，見 IDEAS 2026-10-13）。