Prisma ORM 快速上手：從零到跑通 SQLite 的五分鐘實戰

Prisma ORM 是什麼——給沒聽過它的人

Prisma 是一款面向 Node.js 與 TypeScript 的現代 ORM（物件關係對映）工具。簡單說，它讓你用 TypeScript 來操作資料庫，而不是直接寫 SQL。

傳統上，你要先定義資料表結構、寫 SQL 查詢、再把查詢結果手動轉成 JavaScript 物件。Prisma 把這三件事打包成一套工作流：你在 schema.prisma 檔案裡宣告資料模型，跑一條 prisma generate，它就會幫你生成一個完整型別安全的 Client——之後寫查詢就像在呼叫一般的 TypeScript 函式，編譯器會在寫碼階段就幫你把絕大部分的拼錯欄位、漏寫必要條件這類錯誤攔下來。

這對哪些人有用？如果你正在做 Node.js 後端、全端應用（Next.js、NestJS 等框架都原生支援）、或是任何需要跟資料庫互動的 TypeScript 專案，Prisma 值得你花半天試一試。它支援 PostgreSQL、MySQL、SQLite、MongoDB 等主流資料庫，而且 schema 定義與查詢 API 在不同資料庫之間幾乎一致——換資料庫時幾乎不用重寫應用程式碼。

安裝

Prisma 的安裝分成兩個套件：CLI 工具（負責 schema 管理、migration、generate）和 Client（應用程式裡實際使用的查詢物件）。

先確認你的環境有 Node.js 18 或以上版本。接著在專案目錄底下執行：

npm install prisma --save-dev
npm install @prisma/client

CLI 用 --save-dev 是因為它只在開發與部署階段需要，正式執行時只會載入 @prisma/client。安裝完後跑 npx prisma --version 確認版本追蹤與版本號能正常輸出——如果報 Command not found，八成是 npm install 過程中有錯，往上滾動看紅色錯誤訊息再重跑一次。

Windows 使用者注意：如果安裝時卡在 node-gyp 編譯相關錯誤，通常是因為系統缺 Visual Studio Build Tools，安裝「Desktop development with C++」工作負載再重跑即可。macOS 使用者碰到 gyp: No Xcode or CLT version detected，跑 xcode-select --install 就好。

前置條件與首次初始化

安裝完 Prisma 還不能直接用，你需要初始化一個 Prisma 專案結構。這一步會建立 prisma/schema.prisma（資料模型定義檔）和 .env（環境變數，主要是資料庫連線字串）。

這次我們用 SQLite 來做快速上手——SQLite 是檔案型資料庫，不需要安裝與啟動任何背景服務，所有資料就存在專案目錄底下的一個 .db 檔裡，對原型驗證、課堂作業、小型專案來說最省事。

執行初始化：

npx prisma init --datasource-provider sqlite

這個指令做完後，你應該能看到兩個新檔案：prisma/schema.prisma 和 .env。打開 .env 看一下，裡面已經幫你填好了 DATABASE_URL="file:./dev.db"——這表示資料庫檔案會放在 prisma/dev.db。如果你之後想切換到 PostgreSQL 或 MySQL，只要改這個連線字串，schema 裡的 datasource provider 也要跟著改（改成 postgresql 或 mysql）。

第一步：定義你的第一個資料模型

打開 prisma/schema.prisma，你會看到 Prisma 幫你生成的範例內容。把它全部替換成：

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Task {
  id          Int      @id @default(autoincrement())
  title       String
  description String?
  done        Boolean  @default(false)
  createdAt   DateTime @default(now())
}

這裡我們定義了一個 Task 模型，有五個欄位：主鍵 id（自動遞增）、標題（必填）、描述（可空，帶 ?）、完成狀態（布林，預設 false）、建立時間（預設值是建立當下時間）。

寫到這裡，你可以注意幾件事：欄位型別 Prisma 已經幫你對應好 TypeScript 型別——Int 就是 number，String 就是 string，DateTime 就是 Date。型別名稱都是 Prisma 自己定義的，不是 TypeScript 語法。另外 @id、@default() 這些 @ 開頭的叫做「屬性」（attribute），用來補充欄位的額外規則。

第二步：建立資料表並產生 Client

改完 schema 後，執行：

npx prisma migrate dev --name init

這條指令會做三件事：讀取你的 schema → 在 SQLite 裡建立 Task 資料表（會自動建立 prisma/dev.db 檔案）→ 跑 prisma generate 生成 Prisma Client。--name init 是這次 migration 的名字，之後你每次改 schema 都要給一個不同的名字（例如 add-user-model、rename-title-field）。

執行成功後，你會看到 Prisma 印出 migration 檔案路徑和 generate 成功訊息。現在專案目錄底下多了 prisma/dev.db 和 prisma/migrations/ 目錄——後者存著每次 migration 的 SQL 紀錄，部署到生產環境時用 prisma migrate deploy 就能照著這份紀錄把資料庫結構重建出來。

如果這一步報錯，八成是 schema 裡有語法錯誤。Prisma 會在錯誤訊息裡精確指出哪一行哪一列有問題，修正後重跑 migrate dev 就行。

第三步：寫第一條查詢

建立一個 main.ts 檔案（如果你還沒裝 TypeScript，先跑 npm install typescript ts-node @types/node --save-dev 和 npx tsc --init）：

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

async function main() {
  await prisma.task.create({
    data: { title: '學習 Prisma', description: '寫個 demo' },
  })
  await prisma.task.create({
    data: { title: '提交程式碼' },
  })

  const tasks = await prisma.task.findMany()
  console.log(tasks)
}

main()
  .catch(console.error)
  .finally(() => prisma.$disconnect())

解釋一下這段程式碼：new PrismaClient() 建立一個資料庫連線池實例；prisma.task.create() 對應 INSERT；prisma.task.findMany() 對應 SELECT *；最後一定要在 finally 裡呼叫 prisma.$disconnect() 關閉連線——不然 Node.js 進程會因為連線還開著而不會自動結束。

執行：

npx ts-node main.ts

你應該能在終端看到兩個剛建立的 Task 物件被印出來，每個物件都有完整的欄位值（id 1 和 2、title、description、done: false、createdAt）。這就是 Prisma Client 的威力——你寫的是 TypeScript 物件，Prisma 在底下幫你轉成 SQL、送去 SQLite、再把結果轉回 TypeScript 物件，全程有型別檢查。

第四步：用 Studio 視覺化你的資料

Prisma 內建了一個叫 Studio 的圖形化資料庫瀏覽器：

npx prisma studio

執行後瀏覽器會自動打開 http://localhost:5555，你可以看到 Task 模型、剛才建立的兩條紀錄，並且直接在網頁上篩選、編輯、新增資料。Studio 對開發階段驗證資料結構非常方便——尤其是 schema 改了之後，看 Studio 裡的表格結構就知道 migration 有沒有正確執行。

三個新手最容易翻車的地方

卡點一：執行完 migrate 但 TypeScript 還是報舊型別錯誤。 這多半是 VS Code 的 TypeScript 伺服器快取了舊的 PrismaClient 型別。按 Ctrl+Shift+P 打開指令面板，輸入「TypeScript: Restart TS Server」回車，通常就好。如果還不行，直接重啟 VS Code——這是最乾淨的解法。

卡點二：import { PrismaClient } from '@prisma/client' 報模組找不到。 有兩種可能：你忘了執行 npm install @prisma/client，或是你在 schema 裡自訂了 generator 的 output 路徑。先確認前者，再看 schema.prisma 裡的 generator 區塊有沒有 output = "..." 這一行——有的話 Prisma 不會把 Client 生成到預設的 node_modules/.prisma/client，你要改成從自訂路徑 import。對新手來說，把自訂 output 刪掉、恢復預設行為最省事。

卡點三：從 SQLite 切到 PostgreSQL 後 migration 報錯。 SQLite 和 PostgreSQL 的 SQL 語法與型別系統不完全一致，之前在 SQLite 上生成的 prisma/migrations/ 目錄裡的 SQL 檔案，在 PostgreSQL 上可能跑不通。解法很簡單：先備份 SQLite 的資料，刪掉 prisma/migrations/ 整個目錄，把 schema.prisma 的 datasource provider 改成 postgresql，然後用新資料庫重新執行一次 prisma migrate dev --name init。原型階段這麼做完全沒問題——migration 檔案本質上就是對資料庫結構變更的紀錄，換資料庫就要從頭開始紀錄。

下一步可以玩什麼

跑通 SQLite 之後，你可以試著把資料庫換成 PostgreSQL（把 .env 的 DATABASE_URL 改成 PostgreSQL 連線字串、schema 的 provider 改成 postgresql、重新 migrate）——PostgreSQL 支援 Json 欄位、原生列舉型別、更豐富的索引選項，是生產環境的主力選擇。或者試試 Prisma Accelerate——它在 Prisma 和資料庫之間加一層查詢快取，對高讀取場景的資源優化與效能提升都很明顯，但需要注意它會強制你在 schema 裡加上 directUrl 連線字串（給 CLI 命令繞過快取直連資料庫用）。另外還有 Client Extensions（$extends() 方法）可以幫你給 PrismaClient 加上軟刪除、多租戶隔離、查詢日誌等横切關注點，是中等規模專案很實用的進階能力。

本文為個人基於網路公開資料整理編寫，非官方內容，僅供學習交流參考；軟體版權歸原作者所有，請支持正版；使用過程中遇到問題請查閱官方管道，本文不承擔任何責任。