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 流水线中，使用 deno fmt 的 --check，使其在不修改文件的情况下失败：

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 依赖写入其中。

提交前忘记运行 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 会显示“需要网络访问”错误。请始终授予代码所需的具体权限。

未使用 deno add 添加依赖

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

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