Deno
宗旨
為現代 Deno 專案提供可移植的預設配置,特別是在程式碼庫混合使用 Deno 與 Node 導向工具、需要從舊 Deno 模式進行乾淨遷移、或將 Deno 引入現有 TypeScript 或 Node 儲存庫時。
何時使用此技能
- 編寫 Deno 腳本、伺服器或邊緣運算程式碼。
- 配置
deno.json、任務及依賴來源。 - 調整現有的
tsconfig.json或eslint.config.*檔案以與 Deno 共存。 - 在單一儲存庫中混合使用 Deno 程式碼與 Node 或 TypeScript 程式碼。
- 審查 Deno 權限、測試或執行環境模式。
預設配置
- 使用
deno.json作為 Deno 的權威設定來源。 - 當 Deno 擁有工作流程所有權時,優先使用
deno check、deno task、deno fmt、deno lint和deno test,而非臨時的包裝腳本。 - Deno 的原生工具鏈對於 Deno 擁有的程式碼已足夠;僅當儲存庫同時包含 Deno 邊界之外的 Node 託管套件或腳本時,才使用 Yarn。
- 僅保留
tsconfig.json給 Node 擁有的路徑,或用於 Deno 工作區和目錄範圍無法乾淨表達的 TypeScript 專案圖情況。 - 記住現代 Node 也已透過內建的類型剝離直接執行 TypeScript;選擇 Deno 是基於其執行環境、權限、依賴和工具鏈模型,而不僅僅是為了避免使用
tsc或ts-node。 - 對於 Deno 擁有的檔案,優先使用
deno lint和deno fmt;僅當儲存庫或編輯器確實需要 ESLint 生態系時才添加 ESLint。 - 當用
deno lint取代 ESLint 時,檢查並保留現有 ESLint 的意圖,將其轉移到deno.json的 includes、excludes、lint 規則或記錄的例外中,而不是完全拋棄配置。 - 當用
deno check取代tsc時,檢查現有的tsconfig.json並將相關的編譯器選項、includes、excludes、libs 和嚴格性期望轉移到deno.json或一個範圍明確的保留tsconfig.json中。 - 當需要基於 npm 的編輯器工具(如 ESLint)在 Deno 儲存庫內執行時,設定
nodeModulesDir: "auto"並將命令包裝在deno task中。 - 當 Deno 擁有依賴管理權時,使用
deno add安裝依賴,不要將deno run npm:<package>視為安裝的替代方案。對僅用於開發的 CLI 和工具,使用deno add --dev npm:<package>。 - 對於安裝的 CLI 工具,將
deno task命名為該工具的名稱,並透過二進位檔名稱呼叫,例如,在deno add --dev npm:sample-tool之後,添加"sample-tool": "sample-tool"。 - 在 Deno 擁有的程式碼中,預設優先使用
.ts模組;不要僅僅為了避免 Deno 不需要的建置步驟而降級到 JavaScript。 - 優先使用 JSR 套件、
npm:規範符或明確的導入映射表條目,而不是分散的舊版 URL 導入。 - 當基於 npm 的 CLI 的安裝或後安裝行為無法與一次性執行乾淨合作時,優先使用
nodeModulesDir: "auto",在allowScripts中允許該套件,使用deno add或deno add --dev添加依賴,並從deno task中呼叫已安裝的二進位檔。 - Deno 2 有意相容於
package.json、npm 套件和 Node 內建模組;將 Deno 專用的配置保留在deno.json中,而不是試圖讓tsconfig.json同時承載兩個世界。 - 對於伺服器,優先使用 Web 標準 API 和
Deno.serve。 - 將權限視為一項設計決策,而非事後補救。
任務框架
| 命令或動作 | 內容 | 原因 | 時機 | 預期結果 |
|---|---|---|---|---|
謹慎採用 tsconfig.json 和 ESLint | 決定哪些保留在 Node 擁有的配置中,哪些移至 deno.json。 | 當兩個工具鏈試圖擁有相同檔案時,混合儲存庫會迅速變得嘈雜。 | 在將 Deno 引入現有 TypeScript 或 Node 程式庫時。 | Deno 和 Node 工具鏈各自擁有明確的所有權邊界。 |
配置 deno.json | 在 Deno 的配置檔案中定義任務、編譯器選項和依賴慣例。 | Deno 應擁有自己的工作流程,而非意外地借用 Node 中心的配置。 | 在開始或重構 Deno 專案時。 | Deno 命令和編輯器行為保持一致。 |
| 安裝 Deno 擁有的 npm CLI | 為開發工具執行 deno add --dev npm:<package>,然後添加一個同名任務來呼叫已安裝的二進位檔。 | 依賴、鎖定檔案、本地二進位檔和任務入口點在 Deno 的套件管理器下保持一致。 | 在向 Deno 擁有的工作流程添加程式碼產生器、瀏覽器自動化 CLI、linter 或格式化器等工具時。 | deno.json 和鎖定檔案記錄了依賴,且 deno task <tool> 會執行已安裝的 CLI。 |
| 設定混合邊界 | 在混合儲存庫中分隔 Deno 擁有的路徑和 Node 擁有的路徑。 | 工具衝突是混合儲存庫最常見的失敗原因之一。 | 當 Deno 程式碼與 Node 或 TS 工具程式碼共存時。 | 編輯器和命令不會爭奪相同的檔案。 |
| 審查權限 | 為執行環境存取選擇明確的權限和任務包裝器。 | Deno 的安全模型只有在權限經過深思熟慮時才有幫助。 | 在執行新腳本或公開 Deno CLI 工作流程之前。 | 檔案系統、網路和環境存取是意圖明確且可稽核的。 |
| 排解 Deno 工作流程問題 | 在猜測之前,先使用 Deno 原生檢查、除錯器標誌和模組圖工具。 | 許多 Deno 問題是配置、權限或所有權問題,而非程式碼錯誤。 | 當混合儲存庫或遷移的工具鏈表現異常時。 | 根本原因被縮小到配置、權限或執行環境行為。 |
核心規則
TypeScript、tsconfig.json 和函式庫
- 將 Deno 編譯器設定放在
deno.json的compilerOptions下;不要僅僅為了讓deno check執行而複製完整的 Nodetsconfig.json。 - 現有的 Node 加 TypeScript 工作區可以保留
tsconfig.json;當目錄也包含deno.json或package.json時,Deno 會探查它。 - 如果父級
deno.json定義了compilerOptions,則這些選項優先於重疊的tsconfig.json選項。 - 如果目標是取代
tsc,首先清查目前tsconfig.json的行為。在 Deno 配置中保留有意義的嚴格性、模組解析、JSX、函式庫、include 和 exclude 決策,或記錄為何它們不再適用。 - 在
deno.json中使用compilerOptions.lib來模擬真實的執行環境表面。對於 SSR 或瀏覽器加 Deno 的程式碼,優先使用如["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]的組合;對於 Deno worker,優先使用["deno.worker"]。 - 當 JavaScript 模組需要明確的類型檢查或宣告時,使用
compilerOptions.checkJs、// @ts-check、@ts-types、@ts-self-types或compilerOptions.types。 - 僅當 Node 擁有的資料夾、TS 專案引用或 include/exclude 的粒度仍然需要時,才保留
tsconfig.json。
Linting、格式化與 ESLint
- 對於 Deno 擁有的程式碼,使用
deno lint和deno.json中的lint部分作為預設的 linting 擁有者。 - 對於 Deno 擁有的程式碼,使用
deno fmt和deno.json中的fmt部分作為預設的格式化工具。 deno lint已涵蓋一個受 ESLint 啟發的推薦規則集;不要僅僅出於習慣而保留 ESLint。- 如果目標是取代 ESLint,首先清查目前
eslint.config.*的行為。在 Deno lint/fmt 配置中保留有意義的檔案範圍、全域變數、忽略和規則意圖,或記錄哪些規則被故意放棄,因為 Deno 已涵蓋或拒絕它們。 - 如果需要自訂的 Deno 專有規則,考慮使用
lint.plugins;請注意 lint 外掛程式 API 是實驗性的,需要 Deno 2.2 或更新版本。 - 如果儲存庫或編輯器仍然需要 ESLint,使其成為一個明確的次要工具:設定
nodeModulesDir: "auto",建立eslint.config.js,並將呼叫包裝在deno task中,例如deno task eslint。 - 盡可能為每個檔案集保留一個 lint 擁有者。如果
deno lint和 ESLint 都執行在相同的檔案上,請記錄原因,否則預期會出現重複和衝突的診斷資訊。
Node 相容性與混合儲存庫
- Deno 2 理解
package.json、node_modules、npm 工作區和 Node 內建模組;混合儲存庫是受支援的路徑,而非一種變通方案。 - 現代 Node 也可以直接執行 TypeScript。在混合儲存庫中,根據權限、依賴模型、任務執行器和部署目標來決定 Node 與 Deno 的所有權,而非僅根據 TypeScript 的執行。
- 如果存在
package.json且希望 Deno 自動建立並重新整理node_modules,請設定nodeModulesDir: "auto"。使用package.json時,Deno 2 預設為"manual"。 nodeModulesDir是工作區根目錄的設定;不要嘗試為每個工作區成員單獨設定。- 當 Deno 擁有依賴更新流程時,使用
deno install或deno add。不要假設 Deno 1 的自動安裝行為。 - 在 Deno 擁有的儲存庫中,對僅用於開發的 npm CLI 使用
deno add --dev npm:<package>。添加後,透過deno task公開二進位檔,例如"sample-tool": "sample-tool",而不是"sample-tool": "deno run -A npm:sample-tool"。 - 將
deno add產生的清單和鎖定檔案更新納入版本控制;僅有任務別名不等於安裝了依賴。 - 如果只有一個子樹是 Deno,不要為整個混合工作區啟用 Deno 工具鏈。
- 優先使用基於路徑的編輯器激活方式,例如
deno.enablePaths,這樣 Node 和 Deno 工具鏈就不會爭奪相同的檔案。 - 在資料夾結構、任務和文件中保持 Deno 邊界明確。
權限、環境與安全性
- 優先使用狹義的
--allow-*標誌或在deno.json中命名的權限集,而非-A。 - 當儲存庫在
deno.json中定義了權限集時,使用-P或--permission-set=<name>。 - 當 CLI 應載入
.env檔案時使用--env-file,或當程式本身需要載入時使用@std/dotenv;兩者仍需要明確的環境和檔案權限。 - 對應用程式程式碼優先使用最小權限,並在任務和範例中讓環境、檔案系統、網路和子程序存取顯而易見。
- 將
--allow-run和--allow-ffi視為沙箱逃逸機制。除非明確意圖完全信任,否則避免使用--allow-run=deno。 - 對於權限除錯或稽核,使用
DENO_TRACE_PERMISSIONS=1和DENO_AUDIT_PERMISSIONS=<path>。
排錯與遷移
- 當運行時成功和類型檢查行為不一致時,使用
deno check、deno check --all或deno run --check。 - 使用
deno info <entrypoint>檢查模組圖並了解導入、快取和權限行為。 - 在逐一手動編輯每個 lint 問題之前,使用
deno lint --fix進行常見的遷移清理。 - 對於除錯器設定,當程序生命週期短暫時使用
--inspect-brk,當檢查器或模組解析令人困惑時使用--log-level=debug,當執行環境掛起或異常緩慢時使用--strace-ops。 - 當排錯問題實際上與效能有關時,使用 CPU 分析標誌,例如
--cpu-prof、--cpu-prof-md或--cpu-prof-flamegraph。 - 遷移建議應反映 Deno 2 的預設值:
nodeModulesDir現在使用"none" | "auto" | "manual",deno cache變成了deno install --entrypoint,deno vendor變成了"vendor": true,Deno.run()應變為new Deno.Command(),且Deno.serveHttp()應變為Deno.serve()。 - 使用導入屬性,例如
with { type: "json" },而不是已棄用的導入斷言。
常見陷阱
- 如果 Deno 和 Node 工具鏈都聲稱擁有相同的檔案,編輯器診斷資訊會變得嘈雜且誤導。
- 如果存在
package.json,Deno 2 會將nodeModulesDir預設為"manual";忘記這點是基於 npm 的工具看起來半安裝狀態的常見原因。 - 如果 VS Code ESLint 擴展是工作流程的一部分,它無法單獨從 Deno 的全域快取解析套件;它需要一個本地的
node_modules目錄。 deno run預設跳過類型檢查,因此執行通過並不能證明deno check也會通過。- 一個外殼指令到
deno run npm:<package>的deno task是一次性的執行捷徑,並非正確的依賴安裝。不要將其作為在 Deno 擁有的儲存庫中「安裝並設定此 CLI」的預設答案。 - 對於受信任的工具,
-A是可接受的,但它不是普通應用程式程式碼的正確預設值。 - 某些 npm CLI,包括實際混合執行環境儲存庫中的 Supabase,依賴於安裝時的行為,這可能透過
deno run npm:...比透過node_modules下已安裝的二進位檔更不可靠。 - 舊的 URL 導入和整個工作區激活模式是過渡輔助工具,而非現代預設值。
驗證
deno.json擁有 Deno 配置和任務的所有權。- 任何保留的
tsconfig.json或 ESLint 所有權都是明確的,且範圍限定在正確的檔案。 - 取代 ESLint 或
tsc保留了現有配置中的有用行為,或記錄了為何有意拋棄它。 - 混合儲存庫中 Deno 和 Node 的部分不會爭奪工具鏈。
- 依賴規範符是現代且明確的。
- Deno 擁有的 npm CLI 是使用
deno add或deno add --dev添加的,記錄在清單和鎖定檔案中,並透過呼叫已安裝二進位檔名稱的任務執行。 nodeModulesDir、編輯器激活和任何基於 npm 的 Deno 工具鏈都已正確配置。- 如果 npm CLI 是從 Deno 任務驅動的,儲存庫會特意配置
nodeModulesDir和allowScripts,而不是依賴於偶然的安裝副作用。 - 權限是意圖明確的,並在重要之處有文件記錄。
- 排錯指導從 Deno 原生檢查開始,然後才回退到通用的 Node 或 TypeScript 除錯建議。
參考資料
- 當任務涉及
tsconfig.json、ESLint、混合 Deno 或 Node 遷移、或排錯 Deno 邊界時,請閱讀./references/adoption-playbook.md。 - Deno LLM 摘要:https://docs.deno.com/llms-summary.txt
- Deno 配置參考:https://docs.deno.com/runtime/fundamentals/configuration/
- Deno TypeScript 配置參考:https://docs.deno.com/runtime/reference/ts_config_migration/
- Deno 安全參考:https://docs.deno.com/runtime/fundamentals/security/
- 閱讀 `./references/che
…
[為翻譯而截斷]