DefinitelyTyped 如何構建和發佈 @types 套件

DefinitelyTyped｜1｜DefinitelyTyped 的用途

DefinitelyTyped 是一個儲存 TypeScript 宣告檔案的儲存庫。README 稱其為高品質 TypeScript 類型定義的儲存庫，但也表示其目標不是覆蓋每個 npm 套件。相反，它針對的是 TypeScript 作者實際使用的套件。貢獻者必須打算在自己的專案中使用這些類型；沒有具體使用動機的 PR 會被關閉。該儲存庫最近改為 pnpm monorepo，改變了套件的佈局。

DefinitelyTyped/DefinitelyTyped 的第 1 個核對點要回到專案本身：它以 TypeScript 為主要語言，預設分支是 master，素材標示的授權為 。README 明列的命令、模組名稱、設定鍵與資料格式，才是這一節能確認的範圍；效能上限、部署規模、外部整合與可靠性若沒有文件依據，就只能保留為未知。

實際檢查時，請在隔離環境執行 DefinitelyTyped/DefinitelyTyped README 的安裝或最小範例命令，保存完整終端輸出，並把輸入、產物位置、退出狀態與錯誤訊息分開記錄。對版本相關行為，再以 DefinitelyTyped/DefinitelyTyped 的 GitHub Releases 標記核對；若 README 指向特定檔案或設定，逐一確認該檔案在目前版本存在，不能以相似專案的慣例補足。這些記錄只說明 DefinitelyTyped 這一項入口是否按文件運作，不代表其他未測試介面也具備相同結果。

DefinitelyTyped/DefinitelyTyped 第 1 次檢查應保存 README 指定命令的完整輸出，核對輸入格式、產物路徑、退出狀態與錯誤訊息，並標記目前版本是否重現文件描述。未被 DefinitelyTyped 文件列出的能力仍不可視為承諾。

DefinitelyTyped｜2｜安裝 @types 套件

該儲存庫的類型定義發佈到 npm 的 @types 作用域。對於 npm 套件 foo，其類型位於 @types/foo。推薦的安裝方法是例如 npm install --save-dev @types/node。對於作用域套件，去掉 @ 並在作用域後添加雙底線，所以 @babel/preset-env 變為 @types/babel__preset-env。編譯器通常會自動包含類型；如果你不使用模組，可能需要三重斜線引用，如 /// <reference types="node" />。README 指向 TypeScript 手冊以獲取詳細資訊。

DefinitelyTyped/DefinitelyTyped 的第 2 個核對點要回到專案本身：它以 TypeScript 為主要語言，預設分支是 master，素材標示的授權為 。README 明列的命令、模組名稱、設定鍵與資料格式，才是這一節能確認的範圍；效能上限、部署規模、外部整合與可靠性若沒有文件依據，就只能保留為未知。

DefinitelyTyped/DefinitelyTyped 第 2 次檢查應保存 README 指定命令的完整輸出，核對輸入格式、產物路徑、退出狀態與錯誤訊息，並標記目前版本是否重現文件描述。未被 DefinitelyTyped 文件列出的能力仍不可視為承諾。

DefinitelyTyped｜3｜受支援的 TypeScript 版本

DefinitelyTyped 只在不到兩年的 TypeScript 版本上測試套件。npm 上的套件有用於舊版 TypeScript 的 dist-tags，因此使用舊編譯器的使用者仍可取得相容宣告；README 展示了 @types/react 的範例，其中 TypeScript 2.5 使用 15.0.1 版本。對於 TypeScript 1.*，必須從 master 分支手動下載定義，並且舊的 Typings 和 NuGet 發佈管道已棄用或關閉。當前支援窗口在 README 的支援窗口圖片中記錄。

DefinitelyTyped/DefinitelyTyped 的第 3 個核對點要回到專案本身：它以 TypeScript 為主要語言，預設分支是 master，素材標示的授權為 。README 明列的命令、模組名稱、設定鍵與資料格式，才是這一節能確認的範圍；效能上限、部署規模、外部整合與可靠性若沒有文件依據，就只能保留為未知。

DefinitelyTyped/DefinitelyTyped 第 3 次檢查應保存 README 指定命令的完整輸出，核對輸入格式、產物路徑、退出狀態與錯誤訊息，並標記目前版本是否重現文件描述。未被 DefinitelyTyped 文件列出的能力仍不可視為承諾。

DefinitelyTyped｜4｜如何測試貢獻

在提交定義之前，貢獻者需要針對真實程式碼進行測試。README 建議建立本機宣告檔案並填寫匯出，或直接在 node_modules 中編輯類型以快速驗證。對於新套件，可以在 tsconfig.json 中設定 baseUrl 和 typeRoots，建立 types/foo/index.d.ts，然後建置並執行程式碼以確認類型與執行時行為相符。測試後，貢獻者 fork、複製、執行 pnpm install，然後發起拉取請求。儲存庫使用機器人自行處理許多 PR，並連結了生命週期圖。

DefinitelyTyped/DefinitelyTyped 的第 4 個核對點要回到專案本身：它以 TypeScript 為主要語言，預設分支是 master，素材標示的授權為 。README 明列的命令、模組名稱、設定鍵與資料格式，才是這一節能確認的範圍；效能上限、部署規模、外部整合與可靠性若沒有文件依據，就只能保留為未知。

DefinitelyTyped/DefinitelyTyped 第 4 次檢查應保存 README 指定命令的完整輸出，核對輸入格式、產物路徑、退出狀態與錯誤訊息，並標記目前版本是否重現文件描述。未被 DefinitelyTyped 文件列出的能力仍不可視為承諾。

DefinitelyTyped｜5｜套件結構和品質檢查

每個 @types 套件都有必需的結構：index.d.ts、一個 <my-package>-tests.ts 檔案（僅進行類型檢查，不執行）、tsconfig.json、.npmignore 和 package.json。測試使用 dtslint，它執行 TypeScript 編譯器對宣告進行檢查。dtslint 還包含 @arethetypeswrong/cli 的模組格式檢查，在 npm 上存在 SemVer 主版本相容的實作套件時與實作套件進行比較。某些套件未能通過這些檢查，列在 attw.json 中；修復後將其從失敗清單中移除。tsconfig.json 必須啟用嚴格選項，並且不允許 esModuleInterop 或 allowSyntheticDefaultImports。

DefinitelyTyped/DefinitelyTyped 的第 5 個核對點要回到專案本身：它以 TypeScript 為主要語言，預設分支是 master，素材標示的授權為 。README 明列的命令、模組名稱、設定鍵與資料格式，才是這一節能確認的範圍；效能上限、部署規模、外部整合與可靠性若沒有文件依據，就只能保留為未知。

DefinitelyTyped｜6｜版本控制、所有權和許可

master 分支由 DefinitelyTyped-tools 自動發佈到 npm 的 @types 作用域。宣告套件版本使用函式庫的 major.minor 後跟 .9999；例如 @types/node 20.8.9999 對應到 20.8.x 線。修補版本獨立遞增。破壞性變更以修補修訂形式發佈，除非伴隨主版本或次版本提升。每個 package.json 中列出定義所有者，並每週同步到 .github/CODEOWNERS。該專案根據 MIT 許可，每個定義檔案的版權歸其貢獻者所有。許可允許自由使用、修改和散佈，但軟體按原樣提供，不提供任何擔保。

DefinitelyTyped/DefinitelyTyped 的第 6 個核對點要回到專案本身：它以 TypeScript 為主要語言，預設分支是 master，素材標示的授權為 。README 明列的命令、模組名稱、設定鍵與資料格式，才是這一節能確認的範圍；效能上限、部署規模、外部整合與可靠性若沒有文件依據，就只能保留為未知。

編輯結論

DefinitelyTyped 是一個社群維護的 monorepo，將 TypeScript 定義發佈到 npm 的 @types 作用域，具有嚴格的貢獻指南和與所描述函式庫關聯的版本控制方案。 對 DefinitelyTyped/DefinitelyTyped 而言，適合能管理 TypeScript 執行環境並願意依 README 入口核對結果的開發者；不適合把倉庫描述當成跨平台、跨版本或效能保證。先執行 DefinitelyTyped/DefinitelyTyped README 的最小命令，記下 master 版本下的輸入、輸出與錯誤，再依文章列出的檔案和設定鍵決定是否導入。 對修改、散布或託管方式的限制，也要配合你的交付模式逐項確認。

官方來源

1. Official README
2. Project repository
3. Release notes