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。
- 仅针对 Node 拥有的路径或 TypeScript 项目图谱(Deno 工作区和目录范围无法清晰表达的情况)保留
tsconfig.json。 - 记住现代 Node 也通过内置的类型剥离直接运行 TypeScript;选择 Deno 是出于其运行时、权限、依赖和工具模型,而不仅仅是为了避免使用
tsc或ts-node。 - 对于 Deno 拥有的文件,优先使用
deno lint和deno fmt;仅当仓库或编辑器确实需要 ESLint 生态系统时才添加 ESLint。 - 当用
deno lint替换 ESLint 时,检查现有 ESLint 意图,并将其转移到deno.json的包含、排除、lint 规则或文档化例外中,而不是直接丢弃配置。 - 当用
deno check替换tsc时,检查现有的tsconfig.json,将相关的编译器选项、包含、排除、库和严格性期望转换为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、库、包含和排除决策,或记录为什么它们不再适用。 - 使用
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 拥有的文件夹、TypeScript 项目引用或包含/排除粒度仍然需要时,才保留
tsconfig.json。
Linting、格式化和 ESLint
- 使用
deno lint和deno.json中的lint部分作为 Deno 拥有代码的默认 lint 所有者。 - 使用
deno fmt和deno.json中的fmt部分作为 Deno 拥有代码的默认格式化程序。 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是一次性执行快捷方式,而不是正确的依赖安装。不要将其视为“安装并设置此 CLI”在 Deno 拥有仓库中的默认答案。 -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 工具都经过有意配置。- 如果从 Deno 任务驱动 npm CLI,仓库有意配置
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(内容已截断)