Prisma ORM 為什麼會在 Node Modules 中生成程式碼以及它將如何改變

為什麼 Prisma ORM 會將 Prisma Client 程式碼生成到 node_modules 中

自首次釋出以來，Prisma ORM 一直使用程式碼生成來生成一個針對資料庫模式量身定製的資料庫客戶端（稱為“Prisma Client”）。Prisma Client 庫根據 Prisma 模式自動生成，因此它瞭解其結構並能為它們提供自定義的、型別安全的查詢。

程式碼生成在 TypeScript 生態系統中並不是最常用的方法，而 Prisma ORM 是首批依賴它的流行庫之一。為了最大程度地提高開發者的熟悉度，我們決定預設將 Prisma Client 生成到 node_modules 資料夾中，因為開發者習慣於透過這種方式在其應用程式中整合第三方庫。

儘管從一開始就可以透過 output 欄位為生成的程式碼選擇自定義位置，但這種預設設定使我們在 Prisma ORM 的各種框架和使用場景中獲得了統一的行為。

預設將 Prisma Client 生成到 node_modules 中，最終為大多數人帶來了神奇的“它就是能用™️”的開發者體驗……除非它不能用！

為什麼以及我們如何在 v7 版本中改變 Prisma Client 的位置

從那時起，開發者因為 node_modules 中生成的程式碼而遇到了問題。JS/TS 生態系統中的許多工具都基於 node_modules 目錄不會被修改（除了透過包管理器（npm、pnpm、yarn 等））的假設進行操作。

然而，使用 Prisma ORM 時，您需要在每次資料庫模式更改後重新生成 Prisma Client，以便生成的程式碼反映資料庫的最新狀態。這一要求，加上預設將生成的程式碼放入 node_modules 的選擇，違反了生態系統中許多工具的假設。

將生成程式碼放入 node_modules 時所需的變通方法

因為許多工具都基於 node_modules 僅由包管理器修改的假設進行操作，所以我們（以及社群中的其他人）採取了變通方法以確保流暢的開發者體驗（DX）。

例如，由於 TS 語言伺服器不監視 node_modules 中的更改，我們調整了 Prisma VS Code 擴充套件，以便您每次執行 prisma generate 時都重新啟動 TS 語言伺服器。另一個例子是 @prisma/nextjs-monorepo-workaround-plugin 包，其唯一目的是確保當 Prisma ORM 在使用 Next.js 的 monorepos 中使用時，檔案能從 node_modules 正確複製。

針對生成程式碼位於 node_modules 這一核心問題的變通方法多種多樣，從專門的包到硬編碼的程式碼路徑都有。

未來將有哪些改變？

儘管最初決定將 Prisma Client 生成到 node_modules 中幫助了許多開發者入門並提供了流暢、統一的開發者體驗，但我們也看到這種“神奇”的行為常常導致開發者在使用 Prisma ORM 時遇到意想不到的問題。

我們目前正在透過移除“神奇”行為或不必要的抽象層，使 Prisma ORM 的開發者體驗更簡單、更可預測。

作為這項舉措的一部分，我們將移除將程式碼生成到 node_modules 中的選項，轉而始終要求提供一個 output 路徑。

為了預見這一變化，我們在 v6.6.0 版本中添加了一個棄用警告，並修改了我們的文件。這在社群中引起了一些不必要的困惑，有關詳情請閱讀下一節。

這一改變將於今年晚些時候作為 Prisma ORM v7 的一部分推出，並且隻影響新的 prisma-client 生成器。這種方法有幾個優點：

• 生成的程式碼將被視為“常規”應用程式程式碼：開發者將對其擁有完全控制權，並可以決定它如何成為其應用程式包的一部分。
• 更高的可預測性，並且不再需要因“神奇”行為而採取變通方法。
• 符合 node_modules 只能由包管理器修改的假設。

prisma-client 與 prisma-client-js 生成器

如果您關注了我們的釋出，您會知道在 v6.6.0 版本中，我們釋出了一個新的生成器，簡稱為 prisma-client。

這個新的生成器支援 ESM，與各種 JS 執行時相容，總體上更靈活，並且*要求*使用自定義的 output 路徑。

在 Prisma ORM v7 中，它將成為 Prisma ORM 的預設生成器，而當前的 prisma-client-js 生成器（帶有“神奇”的 node_modules 生成功能）將進入維護模式。

自 v6.6.0 以來設定 output 路徑的困惑

為了預見 v7 中即將到來的變化，我們希望透過引導開發者不再依賴將 Prisma Client 生成到 node_modules 中，來幫助他們為強制 output 路徑這一破壞性變更做好準備。

因此，在最近釋出的 v6.6.0 版本中，當您未使用 prisma-client-js 生成器的自定義 output 路徑時，我們在 Prisma CLI 輸出中引入了以下棄用警告：

我們還更改了執行 prisma init 時生成的預設 Prisma 模式，使其包含一個 output 路徑，並相應地更新了我們的文件。

儘管我們預期這種引導只會帶來積極影響，因為它移除了不可預測的、有問題的行為並賦予了開發者更多控制權，但許多人在看到棄用警告並切換到將 output 路徑與 prisma-client-js 生成器一起使用後，實際上報告了問題。

使用者開始報告 src/generated/prisma 中的 linting 失敗，這在使用 Next.js 開發伺服器時尤其成問題，因為它會在檢測到 linting 錯誤時暫停操作。由於程式碼是生成的，linting 錯誤實際上並不重要，但使用者預設沒有將 src/generated 從他們的 linting 配置中排除。

其他使用者報告了其打包器（bundler）、相對路徑解析以及許多其他意外副作用的問題。總之，我們看到關於在哪裡生成 Prisma Client 以及如何打包它存在很多困惑。

所有這些問題都發生在使用 node_modules 中的 Prisma Client 時執行正常的專案上。為了在 v7 釋出前避免此類問題，我們再次從 CLI 輸出中移除了棄用警告，並將修復社群提出的問題。

今天何時在 Prisma ORM 中使用自定義 output 路徑

以下是所有這些對您今天意味著什麼的簡要概括：

• 如果您有一個使用 Prisma ORM 並正在使用 prisma-client-js 生成器的現有專案
  • 如果您最近添加了自定義的 output 路徑並因此看到錯誤，您可以像以前一樣恢復將 Prisma Client 生成到 node_modules 中。
  • 如果您的 Prisma ORM 在將 Prisma Client 生成到 node_modules 中時目前執行良好，則無需進行任何更改。Prisma ORM v7 將引入新的 prisma-client 生成器，作為使用帶有 output 路徑的 Prisma ORM 的預設方式。到時候，將提供詳細的升級路徑文件。
• 如果您今天開始一個新專案，我們建議設定一個自定義的 output 路徑，以避免打包問題併為 Prisma ORM v7 中即將到來的破壞性更改做準備。由於生成的資產（大部分）是原始碼，旨在被處理幷包含在您的應用程式包中，我們建議使用應用程式原始碼樹內的路徑（例如 src/generated/prisma）。
• 如果您在使用 output 路徑時遇到問題（無論您使用的是新的 prisma-client 還是當前的 prisma-client-js 生成器），請提交一個新 issue，以便我們幫助您解決問題。

如果您有任何反饋或問題，一如既往地可以透過 X 聯絡我們或加入我們的 Discord！