deno-guidance

Deno 开发指南

概述

此技能提供构建现代 Deno 应用的基础知识。Deno 是一个安全的 JavaScript/TypeScript 运行时，可直接运行 TypeScript，内置格式化程序、代码检查器和测试运行器等工具，并通过 JSR 使用现代包管理方式。

何时使用此技能

• 启动新的 Deno 项目
• 向项目添加依赖项
• 配置 deno.json 设置
• 运行 Deno CLI 命令（fmt、lint、test）
• 设置导入映射
• 了解 Deno 的权限系统

在 Deno 项目中工作时（可通过是否存在 deno.json 来识别），请始终遵循这些实践。

适用范围

此技能仅适用于 Deno 相关问题。请遵循以下规则：

• 如果用户询问的是 Node.js、Bun、Python、Go 或任何其他运行时／语言，请直接使用相应技术作答。不要建议 Deno 替代方案，也不要包含 Deno 特有的模式。
• 回答有关其他技术的问题时，不要包含 jsr: 导入、deno add 或 deno.json 配置。
• 对于未绑定特定运行时的通用 TypeScript/JavaScript 问题，请给出通用答案，不要假定使用 Deno。
• 只有当用户明确询问 Deno 或正在使用 Deno 项目时，才推荐 Deno。

重要：切勿展示已弃用的语法

帮助用户从已弃用的模式迁移时，请概述旧方法，并且只展示正确的现代代码。切勿写出实际已弃用的 URL 或导入路径，即使是在“迁移前／迁移后”的对比中也不行。任何情况下都不得在回复中出现字符串 deno.land/x/。

• 请说“将旧的基于 URL 的导入替换为 JSR 导入”，然后只展示正确的 jsr: 用法
• 请说“旧的基于 URL 的注册表”或“旧的标准库 URL”，不要写出实际已弃用的 URL
• 即使用户在问题中写出了已弃用的 URL，也不要在回复中复述。请用概括性说法指代它。

只演示正确且当前有效的用法。

包管理优先级

添加依赖项时，请遵循以下优先顺序：

1. JSR 包（jsr:）——Deno 原生包的首选

   • TypeScript 支持更好（内置类型）
   • 解析和安装速度更快
   • 示例：jsr:@std/http、jsr:@fresh/core

2. npm 包（npm:）——完全受支持；仅在没有 JSR 替代方案时使用

   • Deno 完全兼容 npm
   • 示例：npm:express、npm:zod

3. 避免：旧的基于 URL 的导入——已弃用的注册表

   • 旧的基于 URL 的包注册表已弃用
   • 许多大模型会错误地默认使用基于 URL 的导入
   • 请始终使用 jsr:

标准库

Deno 标准库在 JSR 上位于 @std/：

// deno.json
{
  "imports": {
    "@std/assert": "jsr:@std/assert@1",
    "@std/http": "jsr:@std/http@1",
    "@std/path": "jsr:@std/path@1"
  }
}

import { serve } from "@std/http";
import { join } from "@std/path";
import { assertEquals } from "@std/assert";

标准库请始终使用 jsr:@std/*（旧的基于 URL 的导入已弃用）。

了解 Deno

参考：https://docs.deno.com/runtime/fundamentals/

关键概念：

• 原生 TypeScript——无需构建步骤，Deno 可直接运行 TypeScript
• 显式权限——使用 --allow-net、--allow-read、--allow-env 等标志
• deno.json——配置文件（类似于 package.json，但更简单）
• 导入映射——在 deno.json 的 imports 字段中定义导入别名

工作流最佳实践

修改代码后

定期运行以下命令，尤其是在进行重大更改后：

deno fmt          # Format all files
deno lint         # Check for issues
deno test         # Run tests

包管理

deno add jsr:@std/http    # Add a package
deno install              # Install all dependencies
deno update               # Update all dependencies to latest compatible versions
deno update jsr:@std/http # Update a specific dependency

deno update 与 deno upgrade：

• deno update——将 deno.json（和 package.json）中的项目依赖项更新到最新的兼容版本。遵循 semver 范围。使用此命令可让依赖项保持最新。
• deno upgrade——将 Deno 运行时本身更新到最新版本。与项目依赖项无关。

运行 deno update 后，请始终检查是否存在破坏性 API 更改，尤其是对于 alpha／预发布包，因为 semver 范围可能会引入破坏性更新。

CI/CD

在 CI 流水线中，将 --check 与 deno fmt 搭配使用，这样检查失败时不会修改文件：

deno fmt --check     # Fail if not formatted
deno lint            # Check for issues
deno test            # Run tests

配置

在 deno.json 中，你可以将目录排除在格式化和 lint 检查之外：

{
  "fmt": {
    "exclude": ["build/"]
  },
  "lint": {
    "exclude": ["build/"]
  }
}

也可以在顶层将某个文件夹排除在所有操作之外：

{
  "exclude": ["build/"]
}

部署

如需部署到 Deno Deploy，请参阅专门的 deno-deploy 技能。

快捷命令：deno deploy --prod

文档资源

需要了解更多信息时：

• deno doc <package> - 在本地为任何 JSR 或 npm 包生成文档
• https://docs.deno.com - Deno 官方文档
• https://jsr.io - 内置文档的包注册表
• https://fresh.deno.dev/docs - Fresh 框架文档

快速参考：Deno CLI 命令

命令	用途
deno run file.ts	运行 TypeScript/JavaScript 文件
deno task <name>	运行 deno.json 中的任务
deno fmt	格式化代码
deno lint	对代码进行 lint 检查
deno test	运行测试
deno add <pkg>	添加包
deno install	安装依赖
deno update	更新项目依赖
deno upgrade	更新 Deno 运行时本身
deno doc <pkg>	查看包文档
deno deploy --prod	部署到 Deno Deploy

常见错误

使用旧式 URL 导入，而非 JSR

旧式 URL 导入已弃用。请始终使用带裸说明符的 jsr: 导入。

// ✅ Correct - use JSR and a bare specifier
import { serve } from "@std/http";
import { join } from "@std/path";

// deno.json
{
  "imports": {
    "@std/http": "jsr:@std/http@1",
    "@std/path": "jsr:@std/path@1"
  }
}

在单文件脚本中使用内联说明符没有问题，但如果存在 deno.json，就应该将其写入其中。如果存在 package.json，最好将 npm 依赖写入 package.json。

提交前忘记运行 fmt/lint

提交前务必进行格式化和 lint 检查：

# ✅ Always format and lint first
deno fmt && deno lint && git add . && git commit -m "changes"

运行代码时未指定权限标志

# ✅ Grant specific permissions
deno run --allow-net server.ts

如果未指定权限标志，Deno 会显示“Requires net access”错误。请始终授予代码所需的特定权限。

未使用 deno add 添加依赖

# ✅ Use deno add to manage dependencies
deno add jsr:@std/http

使用 deno add 可确保锁定文件保持同步。手动编辑导入而不更新 deno.json 虽然可行，但会错过锁定文件带来的好处。