aiBorn
登入

Docs

如何使用

從靜態頁、動態網站到 Prompt 範例，一步步把你的內部工具部署上線。

開始使用

建議搭配 Codex、Cursor 等工具撰寫與調整程式碼；先用靜態網站驗證需求與內容，再視需要擴充為動態網站。

先用靜態頁試水溫

先把流程說明、表單嵌入做成靜態頁給部門看；確認用得起來，再決定要不要加後端、資料庫、登入功能。

使用流程建議

  1. 建立專案後，先完成「專案設定」基本資料與封面圖。
  2. 依需求進入「靜態網站」或「動態網站」進行開發與部署。
  3. 部署完成後，到「部署中心」與「版本紀錄」確認上線狀態。

若在開發或部署流程需要協助，請聯繫內部技術窗口，或參考本頁各節說明。

靜態網站

適合品牌頁、活動頁、內容展示頁。建議先上線靜態版本，驗證內容與轉換後再擴展動態功能。

功能說明

  • 使用 HTML + JavaScript + CSS 建立前端頁面。
  • 適合單頁式官網、作品展示、活動報名、個人名片頁。
  • 部署快速、維護成本低，適合先做 MVP 驗證。
  1. 進入「專案編輯 > 靜態網站」。
  2. 以 HTML + JavaScript + CSS 完成頁面內容。
  3. 到「部署中心」點擊發布，取得網站網址。
  4. 每次修改後重新部署，讓線上版本同步更新。

動態網站

適合會員功能、後台管理、資料互動服務。動態網站透過上傳 ZIP（根目錄需包含 Dockerfile）進行部署。

功能說明

  • 支援有後端邏輯的服務，例如會員系統、預約系統、內部管理系統。
  • 專案設定可查看動態網站網址與執行個體資訊；對外一律為子網域網址直連。
  • 可建立 MySQL 資料庫並使用平台提供的連線資訊進行串接。
  • 可查看部署結果與版本紀錄，持續迭代專案。

本機開發環境：Windows 安裝 Node.js

動態網站（Next.js 等）需在本機安裝 Node.js 與 npm，才能執行 npm install、建置與打包 ZIP。

下載（建議 LTS 長期支援版）

安裝步驟

  1. 下載並執行上述 .msi 安裝程式。
  2. 安裝精靈中勾選「Automatically install the necessary tools」（若出現），其餘採預設即可。
  3. 安裝完成後重新開啟「命令提示字元」或 PowerShell。
  4. 確認版本（應顯示版本號，例如 v20.x、v22.x）：
    node -v
npm -v
  5. 於專案資料夾執行 npm install 安裝依賴後再開發或打包上傳。
  1. 進入「專案編輯 > 動態網站」上傳 ZIP。
  2. 填入部署所需 .env（平台不會自動覆寫你的環境變數）。
  3. 可在同頁建立 MySQL，取得資料庫欄位資訊後自行寫入 .env。
  4. 到部署中心查看部署結果與版本紀錄。

部署建議

  • 服務監聽 `0.0.0.0:8080`，並在 Dockerfile 對外提供 8080。
  • 設定信任反向代理（Trust Proxy），確保網址與資源路徑使用正式 HTTPS 網域。
  • 移除 node_modules、vendor、dist、build、.next 等依賴或建置產物再上傳。

常見問題

1. ZIP 上傳失敗（檔名編碼）處理方式

若部署紀錄顯示 bad extra field length (central)、Unicode filename corrupt，通常是 ZIP 內檔名編碼異常。

  1. 優先將檔名改為英文、數字與連字號（避免中文與特殊符號）。
  2. 避免使用可能產生編碼問題的壓縮方式；建議改用 7-Zip 或命令列重打包。
  3. 重打包流程：先完整解壓，再重新壓縮成新 ZIP 後上傳。
  4. 上傳前先驗證 ZIP：unzip -t source-fixed.zip，確認無錯誤再部署。
  5. 避免把 Office 暫存檔與編碼異常檔案放進 ZIP（特別是資料夾內含中文檔名時）。

2. Windows UTF-8 BOM 導致建置異常

另外，Windows 也常見 UTF-8 BOM 問題（特別是 Dockerfile、.sh、.env）。 BOM 可能導致建置腳本或指令解析異常。

  • 文字檔請使用 UTF-8（無 BOM）與 LF 換行格式。
  • VS Code 可在右下角編碼選單改為「UTF-8」，並將行尾改為 LF 後儲存。
  • 若專案來自 Windows，建議在打包前統一轉檔與換行後再壓縮 ZIP。

Prompts資源

以下分為兩種常用情境：建立靜態網站、建立動態網站系統架構。

Prompt：建立靜態網站

你可以直接複製以下範例給 AI，快速產生可用的靜態網站程式碼。

靜態網站 Prompt
請建立一個「活動報名網站」的靜態網站，使用 HTML + CSS + JavaScript。
需求：
1) 首頁區塊：活動標題、時間、地點、主視覺。
2) 活動流程、講者介紹、FAQ、聯絡資訊等內容區塊。
3) 可加入前端互動（例如:選單展開、區塊切換、回到頂部），但不需後端功能。
4) 若有「報名」按鈕，請改為外部連結（例如 Google 表單連結），不要在站內送出資料。
5) RWD 響應式設計（手機與桌機都可讀）。
6) 程式碼請拆為 index.html / styles.css / main.js，風格簡潔、可直接上線展示。

Prompt：建立動態網站系統架構

以下 Prompt 描述技術架構與專案骨架，含 Dockerfile、MySQL 環境變數與容器啟動流程。

建議技術

  • 前端／全端：Next.js + React.js（TypeScript）
  • 資料層：Prisma + MySQL
  • 部署：Dockerfile（根目錄，監聽 8080）
動態網站 Prompt
請規劃一個可部署的動態網站系統架構骨架，技術棧如下。

技術棧（必須採用）：
- Next.js（App Router）+ React.js（TypeScript）
- Prisma + MySQL（mysql2 作為 Node.js MySQL 驅動）
- 根目錄 Dockerfile（容器化部署）

架構設計：
1) 目錄與分層
 - app/：頁面路由、layout、loading／error 邊界
 - app/api/：Route Handlers（REST 風格 JSON API）
 - components/：可重用 UI（Server／Client 元件分離原則）
 - lib/：共用工具、Prisma client 單例、mysql2 連線池單例、環境變數讀取
 - services/ 或 server/：伺服器端邏輯（不直接寫在 route 內）
 - prisma/：schema.prisma、migrations
 - 可選 (admin)/ 或 route group：與公開區分的路由群組

2) 資料存取層（Prisma + mysql2 + MySQL）
 - schema 僅示範通用實體（例如 User、Session 或 AuditLog），說明關聯與索引策略
 - 遷移流程：migrate dev／deploy
 - MySQL 串接程式碼須支援以下環境變數（連線資訊請至「專案編輯 → 動態網站 → 建立資料庫」取得）：
 DATABASE_HOST（DB HOST；線上為專案資料庫的私有 IP）
 DATABASE_PORT（預設 3306）
 DATABASE_NAME
 DATABASE_USER
 DATABASE_PASSWORD
 - 線上連線走 TCP 且須啟用 SSL（例：Prisma 的 DATABASE_URL 加上 ?sslaccept=accept_invalid_certs）
 - lib 內依上述欄位以 DB HOST + SSL 組裝 Prisma 連線（TCP）
 - 使用 mysql2（建議 mysql2/promise）建立連線池單例（如 lib/mysql.ts）
 - Repository 或 db 存取封裝，避免在 UI 直接呼叫 Prisma 或 mysql2

3) API 與前後端邊界
 - 統一錯誤格式、HTTP 狀態碼慣例
 - 請求驗證層（建議 Zod）與型別共用（request／response DTO）
 - Server Actions 或 Route Handlers 擇一為主並說明取捨

4) 身分與權限（架構級）
 - Session／JWT 或 Cookie 策略擇一並說明
 - Middleware 保護需登入的路由群組
 - 角色欄位預留（如 role: user | admin）

5) Dockerfile 與執行模型（本平台動態網站）
 - Dockerfile 放於專案根目錄
 - 服務監聽 0.0.0.0:8080，Dockerfile 須 EXPOSE 8080
 - 設定 Trust Proxy，確保網站產生的網址與靜態資源路徑使用正式 HTTPS 網域
 - 多階段建置：deps → build → runner
 - COPY package.json、package-lock.json；npm ci
 - Next.js production（建議 output: standalone）
 - 容器啟動入口：ENTRYPOINT／CMD 透過 shell script（如 docker-entrypoint.sh）執行啟動前任務後再啟動應用

6) 交付物（架構文件＋最小可跑骨架）
 - 目錄樹與各層職責說明
 - .env.example（含 DATABASE_HOST／PORT／NAME／USER／PASSWORD／SOCKET 說明）、本機啟動步驟（install／migrate／dev）
 - 空白或 placeholder 頁面與 health check API（如 GET /api/health）
 - 完整 Dockerfile、schema.prisma、prisma client 與 mysql2 連線池初始化範例
 - docker-entrypoint.sh（或等效腳本）與 Dockerfile 中的 ENTRYPOINT 設定，啟動流程建議：
 1) npx prisma migrate deploy（套用資料庫 migration）
 2) 選填：npx prisma db seed（僅在 RUN_SEED=true 等環境變數開啟時執行，避免每次重啟重複寫入）
 3) 啟動 Next.js production server（0.0.0.0:8080）
 - 任一步驟失敗應 exit 非 0，避免服務在 schema 未就緒時對外提供流量