导入映射 #

一、导入映射概述 #

导入映射（Import Maps）是一种将模块说明符映射到实际URL的机制。它允许你使用简洁的别名来导入模块，简化代码并统一管理依赖。

二、基本配置 #

2.1 deno.json配置 #

json

{
  "imports": {
    "@std/http": "jsr:@std/http@^1.0.0",
    "@std/fs": "jsr:@std/fs@^1.0.0",
    "lodash": "npm:lodash@^4.17.21"
  }
}

2.2 import_map.json文件 #

json

{
  "imports": {
    "@std/http": "jsr:@std/http@^1.0.0",
    "@std/fs": "jsr:@std/fs@^1.0.0",
    "lodash": "npm:lodash@^4.17.21"
  }
}

使用命令指定：

bash

deno run --import-map=import_map.json main.ts

2.3 使用映射 #

typescript

import { serve } from "@std/http";
import { walk } from "@std/fs";
import _ from "lodash";

serve(() => new Response("Hello World"), { port: 8000 });

三、映射类型 #

3.1 精确映射 #

json

{
  "imports": {
    "lodash": "https://cdn.skypack.dev/lodash@4.17.21",
    "react": "https://esm.sh/react@18.2.0"
  }
}

typescript

import lodash from "lodash";
import React from "react";

3.2 前缀映射 #

json

{
  "imports": {
    "@std/": "https://deno.land/std@0.208.0/",
    "@my-lib/": "./src/lib/"
  }
}

typescript

import { serve } from "@std/http/server.ts";
import { helper } from "@my-lib/utils.ts";

3.3 本地路径映射 #

json

{
  "imports": {
    "@/": "./src/",
    "@utils/": "./src/utils/",
    "@types/": "./src/types/"
  }
}

typescript

import { add } from "@/utils/math.ts";
import { User } from "@types/user.ts";
import { config } from "@/config.ts";

3.4 混合映射 #

json

{
  "imports": {
    "@std/": "https://deno.land/std@0.208.0/",
    "@/": "./src/",
    "lodash": "npm:lodash@^4.17.21",
    "react": "https://esm.sh/react@18.2.0"
  }
}

四、高级用法 #

4.1 作用域映射 #

json

{
  "imports": {
    "lodash": "npm:lodash@4.17.21"
  },
  "scopes": {
    "./legacy/": {
      "lodash": "npm:lodash@3.10.1"
    }
  }
}

typescript

// main.ts - 使用lodash 4.17.21
import _ from "lodash";

// legacy/old.ts - 使用lodash 3.10.1
import _ from "lodash";

4.2 条件映射 #

json

{
  "imports": {
    "env": {
      "browser": "./env.browser.ts",
      "default": "./env.node.ts"
    }
  }
}

4.3 动态映射 #

typescript

// 根据环境动态选择模块
const config = await import(
  Deno.env.get("ENV") === "production" 
    ? "./config.prod.ts" 
    : "./config.dev.ts"
);

五、实际应用 #

5.1 项目结构 #

text

project/
├── deno.json
├── import_map.json
├── src/
│   ├── mod.ts
│   ├── utils/
│   │   └── mod.ts
│   ├── types/
│   │   └── mod.ts
│   └── services/
│       └── mod.ts
└── tests/
    └── mod.test.ts

5.2 deno.json配置 #

json

{
  "name": "@my-org/my-project",
  "version": "1.0.0",
  "exports": "./src/mod.ts",
  "imports": {
    "@std/http": "jsr:@std/http@^1.0.0",
    "@std/testing": "jsr:@std/testing@^1.0.0",
    "@std/fs": "jsr:@std/fs@^1.0.0",
    "@/": "./src/",
    "@utils/": "./src/utils/",
    "@types/": "./src/types/",
    "@services/": "./src/services/"
  },
  "tasks": {
    "dev": "deno run --watch src/mod.ts",
    "test": "deno test --allow-all",
    "build": "deno compile --output dist/app src/mod.ts"
  }
}

5.3 使用示例 #

typescript

// src/mod.ts
import { serve } from "@std/http";
import { helper } from "@utils/mod.ts";
import { User } from "@types/mod.ts";
import { api } from "@services/mod.ts";

serve(() => new Response("Hello World"), { port: 8000 });

六、与deps.ts对比 #

6.1 deps.ts方式 #

typescript

// deps.ts
export { serve } from "https://deno.land/std@0.208.0/http/server.ts";
export { assertEquals } from "https://deno.land/std@0.208.0/testing/asserts.ts";

// 使用
import { serve, assertEquals } from "./deps.ts";

6.2 导入映射方式 #

json

{
  "imports": {
    "@std/": "https://deno.land/std@0.208.0/"
  }
}

typescript

import { serve } from "@std/http/server.ts";
import { assertEquals } from "@std/testing/asserts.ts";

6.3 选择建议 #

小型项目：两种方式都可以
大型项目：推荐使用导入映射
需要灵活别名：使用导入映射

七、最佳实践 #

7.1 统一版本管理 #

json

{
  "imports": {
    "@std/": "https://deno.land/std@0.208.0/",
    "lodash": "npm:lodash@4.17.21",
    "zod": "npm:zod@3.22.4"
  }
}

7.2 使用语义化别名 #

json

{
  "imports": {
    "@/": "./src/",
    "@utils/": "./src/utils/",
    "@types/": "./src/types/",
    "@services/": "./src/services/",
    "@config/": "./src/config/"
  }
}

7.3 区分环境 #

json

{
  "imports": {
    "@config/": "./src/config/"
  },
  "scopes": {
    "./tests/": {
      "@config/": "./src/config/test.ts"
    }
  }
}

八、常见问题 #

8.1 映射不生效 #

bash

# 确保使用正确的配置文件
deno run --config=deno.json main.ts

# 或在deno.json中配置

8.2 缓存问题 #

bash

# 清除缓存
rm -rf ~/.cache/deno

# 重新缓存
deno cache main.ts

8.3 路径问题 #

json

{
  "imports": {
    // 正确：使用相对路径
    "@/": "./src/",
    
    // 错误：缺少./
    // "@": "src/"
  }
}

九、总结 #

本章学习了：

导入映射的基本概念
配置方式（deno.json、import_map.json）
各种映射类型
高级用法（作用域、条件映射）
实际应用场景
与deps.ts的对比
最佳实践

下一章，我们将学习异步编程。