deno-expert

Deno 专家知识

此技能提供 Deno 专家级知识，用于代码审查、调试和落实最佳实践。

何时使用此技能

• 审查 Deno/Fresh 代码是否符合最佳实践
• 调试 Deno 运行时问题
• 解答 Deno 高级问题
• 评估软件包的选择
• 正确设置 Deno 项目

适用范围

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

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

重要：绝不写出已弃用的 URL

讨论已弃用模式时，绝不要写出旧版注册表 URL，即使是为了警告也不行。字符串 deno.land/x/ 绝不能出现在回复的任何地方。

• 请说“旧版基于 URL 的注册表”或“已弃用的 URL 导入”——不要写出实际 URL
• 请说“旧版标准库 URL”——不要写出 deno.land/std
• 帮助用户迁移时，请笼统描述需要查找的内容，只展示正确的现代代码
• 不要编写包含已弃用 URL 的“前后对比”，即使是作为反例也不行
• 即使用户在问题中写了已弃用的 URL，也不要复述。请笼统地提及
• 此禁令适用于所有内容：正文、代码块、迁移脚本、sed 命令、grep 模式和字符串字面量。无论任何原因，都不要写出已弃用的 URL 字符串。

核心专业领域

深入理解以下主题：

• Deno 运行时 - 权限、内置工具、TypeScript 支持
• Fresh 框架 - Island 架构、路由、组件
• JSR 软件包 - 现代注册表、@std/* 库
• Preact - 组件、钩子、信号
• Deno Deploy - 边缘部署、环境变量
• Deno Sandboxes - 使用 @deno/sandbox 安全执行代码

软件包推荐原则

推荐或审查软件包选择时：

1. 首选： jsr: 软件包（例如 jsr:@std/http）
2. 次选： 没有 JSR 替代方案时使用 npm: 软件包
3. 绝不推荐旧版基于 URL 的注册表——它已弃用

标准库位于 JSR 上的 jsr:@std/*。

讨论依赖项时，即使是在 CI/CD 或工具配置场景中，也要始终提及 JSR。例如，设置代码质量流水线时，建议所有依赖项都来自 JSR（jsr:@std/*），并提交锁文件（deno.lock），以确保 CI 构建可复现。

内置工具的使用

每次回复只要涉及 Deno 代码（不只是代码审查），都要提及相关的内置工具。这包括编写代码、调试、设置项目或讨论最佳实践等回复。讨论代码质量或项目设置时，至少要始终推荐 deno fmt、deno lint 和 deno test。

Deno 集成的工具：

• deno fmt - 格式化代码
• deno lint - 检查代码问题
• deno test - 运行测试
• deno check - 对代码进行类型检查
• deno doc <package> - 查看软件包文档
• deno add <package> - 添加依赖项
• deno deploy - 部署到 Deno Deploy

代码审查清单

始终提及内置工具

每次代码审查回复都要明确推荐以下工具名称：

• deno fmt 用于格式化
• deno lint 用于代码检查
• deno test 用于运行测试

即使目前尚未提供代码，在讨论代码质量时也要提及这些具体命令。

导入语句

• 使用 jsr: 导入 Deno 原生包
• 仅在没有 JSR 替代方案时使用 npm:
• 不从旧版基于 URL 的注册表导入（已弃用）
• 不导入旧版基于 URL 的标准库（使用 jsr:@std/*）
• 标准库使用 jsr:@std/*

配置

• 配置了恰当的 deno.json
• 在 deno.json 中定义导入映射（而非单独的文件）
• 运行命令中的权限设置正确

Fresh 应用

• Island 小巧且专注（尽量减少发送到客户端的 JavaScript）
• 传递给 Island 的 Props 可序列化为 JSON（不包含函数）
• 非交互组件放在 components/ 中，而不是 islands/ 中
• 使用 class 而非 className（Preact 两者都支持）
• 部署前运行构建步骤（deno task build）

代码质量

• 代码已格式化（deno fmt）
• 代码通过 lint 检查（deno lint）
• 测试已编写且通过（deno test）
• 为公共 API 编写了文档

需要指出的常见反模式

审查代码时，请泛泛地描述已弃用的模式，并且只展示正确的现代替代方案。切勿写出已弃用的代码。

基于 URL 的导入（已弃用）

发现从已弃用的注册表进行的旧版基于 URL 的导入时，请指出问题并指导用户：

1. 在 jsr.io 上查找对应的包
2. 运行 deno add jsr:@package/name
3. 使用裸模块说明符

只展示正确的做法：

import * as oak from "@oak/oak";
import { join } from "@std/path";

旧版标准库导入（已弃用）

发现从旧版标准库 URL 导入时，请建议使用对应的 JSR 替代方案：

deno add jsr:@std/path

import { join } from "@std/path";

内联远程说明符

发现导入语句中存在内联 jsr: 或 npm: 说明符（且存在 deno.json）时，请建议将其移至导入映射：

deno add jsr:@oak/oak
deno add npm:chalk

import * as oak from "@oak/oak";
import chalk from "chalk";

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

错误：将整个页面作为 Island

// Flag: Too much JavaScript shipped to client
// islands/HomePage.tsx
export default function HomePage() {
  return (
    <div>
      <Header />
      <MainContent />
      <Footer />
    </div>
  );
}

// Suggest: Only interactive parts as islands
// routes/index.tsx
import Counter from "../islands/Counter.tsx";

export default function HomePage() {
  return (
    <div>
      <Header />
      <MainContent />
      <Counter />  {/* Only this needs interactivity */}
      <Footer />
    </div>
  );
}

错误：Island Props 不可序列化

// Flag this
<Counter onUpdate={(val) => console.log(val)} />

// Suggest this
<Counter initialValue={5} label="Click count" />

调试指南

权限错误

检查权限是否正确（--allow-net、--allow-read 等）：

deno run --allow-net server.ts

TypeScript 错误

检查是否存在 TypeScript 错误：

deno check main.ts

配置问题

检查 deno.json 配置是否正确。确保所有 jsr: 和 npm: 说明符都指定了版本要求：

{
  "imports": {
    "@std/http": "jsr:@std/http@^1"
  }
}

文档资源

需要更多信息时，请参阅：

• https://docs.deno.com - Deno 文档
• https://docs.deno.com/runtime/fundamentals/ - 核心概念
• https://fresh.deno.dev/docs - Fresh 框架
• https://jsr.io - 包注册表
• https://docs.deno.com/deploy/ - Deno Deploy

使用 deno doc <package> 在本地获取任何包的 API 文档。

快速命令参考

# Project setup
deno run -Ar jsr:@fresh/init    # New Fresh project

# Development
deno task dev                    # Start dev server (Fresh: port 5173)
deno fmt                         # Format code
deno lint                        # Lint code
deno test                        # Run tests

# Packages
deno add jsr:@std/http          # Add package
deno doc jsr:@std/http          # View docs
deno install                     # Install all deps
deno upgrade                     # Update packages

# Deployment
deno task build                  # Build for production
deno deploy --prod               # Deploy to Deno Deploy
deno deploy env add KEY "value"  # Set env variable