<p align="left"> <a href= "https://github.com/esm-dev/esm.sh/pkgs/container/esm.sh"><img src="https://img.shields.io/github/v/tag/esm-dev/esm.sh?label=Docker&display_name=tag&style=flat&colorA=232323&colorB=232323&logo=docker&logoColor=eeeeee" alt="Docker"></a> <a href="https://discord.gg/XDbjMeb7pb"><img src="https://img.shields.io/discord/1097820016893763684?style=flat&colorA=232323&colorB=232323&label=Discord&logo=&logoColor=eeeeee" alt="Discord"></a> <a href="https://github.com/sponsors/ije"><img src="https://img.shields.io/github/sponsors/ije?label=Sponsors&style=flat&colorA=232323&colorB=232323&logo=&logoColor=eeeeee" alt="Sponsors"></a> </p>

esm.sh

一个全球性、快速且智能的内容分发网络（CDN），用于现代（es2015+）Web 开发。

如何使用

esm.sh 允许您通过简单的 URL 导入 NPM、GitHub 和 JSR 上的 JavaScript ES 模块。无需安装或构建步骤。

import * as mod from "https://esm.sh/PKG[@SEMVER][/PATH]";

使用 import maps，您甚至可以使用裸导入说明符而不是 URL：

<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@18.2.0"
    "react-dom/": "https://esm.sh/react-dom@18.2.0/"
  }
}
</script>
<script type="module">
  import React from "react"; // → https://esm.sh/react@18.2.0
  import { render } from "react-dom/client"; // → https://esm.sh/react-dom@18.2.0/client
</script>

有关导入映射用法的更多详细信息，请参阅 使用导入映射 部分。

支持的注册表

• NPM:

  // 示例
  import React from "https://esm.sh/react"; // 18.3.0 (最新版)
  import React from "https://esm.sh/react@17"; // 17.0.2
  import React from "https://esm.sh/react@beta"; // 19.0.0-beta-94eed63c49-20240425
  import { renderToString } from "https://esm.sh/react-dom@18.3.0/server"; // 子模块

• GitHub (以 /gh/ 开头):

  // 示例
  import tslib from "https://esm.sh/gh/microsoft/tslib@2.6.0"; // '2.6.0' 是 git 标签
  // 或从 GitHub 获取资源文件
  fetch("https://esm.sh/gh/microsoft/fluentui-emoji/assets/Party%20popper/Color/party_popper_color.svg");

• JSR (以 /jsr/ 开头):

  // 示例
  import { encodeBase64 } from "https://esm.sh/jsr/@std/encoding@1.0.0/base64";
  import { Hono } from "https://esm.sh/jsr/@hono/hono@4";

指定依赖项

默认情况下，esm.sh 根据包依赖重写导入说明符。要指定这些依赖的版本，可以添加 ?deps=PACKAGE@VERSION 查询。要指定多个依赖，请用逗号分隔，如：?deps=react@17.0.2,react-dom@17.0.2。

import React from "https://esm.sh/react@17.0.2";
import useSWR from "https://esm.sh/swr?deps=react@17.0.2";

别名依赖项

import useSWR from "https://esm.sh/swr?alias=react:preact/compat";

与 ?deps 结合使用：

import useSWR from "https://esm.sh/swr?alias=react:preact/compat&deps=preact@10.5.14";

树摇优化

默认情况下，esm.sh 导出一个包含所有导出成员的模块。但是，如果您只想导入特定的成员集，可以通过在导入语句中添加 ?exports=foo,bar 查询来指定它们。

import { __await, __rest } from "https://esm.sh/tslib"; // 7.3KB
import { __await, __rest } from "https://esm.sh/tslib?exports=__await,__rest"; // 489B

通过使用此功能，您可以利用 esbuild 的树摇优化功能，实现更小的包大小。注意，此功能仅支持 ESM 模块，不支持 CJS 模块。

打包策略

默认情况下，esm.sh 会打包未在 exports 字段中声明的子模块。

打包子模块可以减少网络请求数量，提高性能。但是，它可能会重复打包共享模块。在极端情况下，它可能会破坏包的副作用，或改变 import.meta.url 的语义。为避免这种情况，您可以添加 ?bundle=false 来禁用默认的打包行为：

import "https://esm.sh/@pyscript/core?bundle=false";

对于包作者，您可以通过在 package.json 中添加 esm.sh 字段来覆盖打包策略：

{
  "name": "foo",
  "esm.sh": {
    "bundle": false // 禁用默认的打包行为
  }
}

esm.sh 还支持 ?bundle=all 查询，将模块与所有外部依赖项（除了 peerDependencies 中的）打包成一个单独的 JS 文件。

import { Button } from "https://esm.sh/antd?bundle=all";

开发模式

import React from "https://esm.sh/react?dev";

使用 ?dev 选项，esm.sh 会构建一个将 process.env.NODE_ENV 设置为 "development" 的模块，或根据 exports 字段中的 development 条件进行构建。这对于在开发和生产环境中有不同行为的库很有用。例如，React 在开发模式下使用不同的警告消息。

ESBuild 选项

默认情况下，esm.sh 通过检查 User-Agent 标头来确定构建目标。您也可以通过添加 ?target 来指定 target，可用的目标有：es2015 - es2022、esnext、deno、denonext 和 node。

import React from "https://esm.sh/react?target=esnext";

esbuild 支持的其他选项：

• 条件

  import foo from "https://esm.sh/foo?conditions=custom1,custom2";

• 保留名称

  import foo from "https://esm.sh/foo?keep-names";

• 忽略注释

  import foo from "https://esm.sh/foo?ignore-annotations";

Web Worker

esm.sh 支持 ?worker 查询来将模块作为 Web Worker 加载：

import createWorker from "https://esm.sh/monaco-editor/esm/vs/editor/editor.worker?worker";

// 创建一个 worker
const worker = createWorker();
// 通过添加 `name` 选项重命名 worker 以便调试
const worker = createWorker({ name: "editor.worker" });
// 向 worker 注入代码
const worker = createWorker({ inject: "self.onmessage = (e) => self.postMessage(e.data)" });

您可以使用 ?worker 查询从 esm.sh 将任何模块导入为 worker。此外，您可以在 inject 代码中访问模块的导出。例如，使用 xxhash-wasm 在 worker 中哈希字符串：

import createWorker from "https://esm.sh/xxhash-wasm@1.0.2?worker";

// 变量 '$module' 是导入的 'xxhash-wasm' 模块
const inject = `
const { default: xxhash } = $module
self.onmessage = async (e) => {
  const hasher = await xxhash()
  self.postMessage(hasher.h64ToString(e.data))
}
`;
const worker = createWorker({ inject });
worker.onmessage = (e) => console.log("哈希值为", e.data);
worker.postMessage("正在被哈希的字符串");

注意：inject 参数必须是有效的 JavaScript 代码，并且它将在 worker 上下文中执行。

包 CSS

<link rel="stylesheet" href="https://esm.sh/monaco-editor?css">

这仅在包在 JS 中直接导入 CSS 文件时有效。

将 WASM 作为模块导入

esm.sh 支持在 JS 中直接导入 wasm 模块，要做到这一点，您需要在导入 URL 中添加 ?module 查询：

import wasm from "https://esm.sh/@dqbd/tiktoken@1.0.3/tiktoken_bg.wasm?module";

const { exports } = new WebAssembly.Instance(wasm, imports);

注意：*.wasm?module 模式要求浏览器支持 顶级 await 功能。

使用导入映射

导入映射已得到大多数现代浏览器和Deno的原生支持。这使得_裸导入说明符_，如import React from "react"，能够正常工作。

esm.sh引入了?external查询参数来指定外部依赖。通过使用这个查询，esm.sh保持导入说明符不变，让浏览器/Deno根据导入映射来解析。例如：

<script type="importmap">
{
  "imports": {
    "preact": "https://esm.sh/preact@10.7.2",
    "preact/": "https://esm.sh/preact@10.7.2/",
    "preact-render-to-string": "https://esm.sh/preact-render-to-string@5.2.0?external=preact"
  }
}
</script>
<script type="module">
  import { h } from "preact";
  import { useState } from "preact/hooks";
  import { render } from "preact-render-to-string";
</script>

或者，你可以通过在包名前添加*前缀来将所有依赖标记为外部：

{
  "imports": {
    "preact": "https://esm.sh/preact@10.7.2",
    "preact-render-to-string": "https://esm.sh/*preact-render-to-string@5.2.0",
    "swr": "https://esm.sh/*swr@1.3.0",
    "react": "https://esm.sh/preact@10.7.2/compat"
  }
}

导入映射支持尾斜杠，但这与URL搜索参数不兼容。为了解决这个问题，esm.sh提供了一种特殊的导入URL格式，允许你在尾斜杠后使用查询参数：将查询前缀?改为&并放在包版本之后。

{
  "imports": {
    "react-dom": "https://esm.sh/react-dom@18.2.0?dev",
    "react-dom/": "https://esm.sh/react-dom@18.2.0&dev/"
  }
}

逃生舱：原始源文件

在极少数情况下，你可能想要请求包中的JS源文件，而不将其转换为ES模块。要做到这一点，你需要在请求URL中添加?raw查询。

<script src="https://esm.sh/p5/lib/p5.min.js?raw"></script>

你也可以使用raw.esm.sh/<路径>作为源，这等同于esm.sh/<路径>?raw，原始资产中的传递引用也将是原始请求。

Deno兼容性

esm.sh是一个Deno友好的CDN，它解析Node的内置模块（如fs、os、net等），使其与Deno兼容。

import express from "https://esm.sh/express";

const app = express();
app.get("/", (req, res) => {
  res.send("Hello World");
});
app.listen(3000);

Deno通过X-TypeScript-Types头支持package.json文件中具有types字段的模块的类型定义。这使得在Deno中使用这些模块时可以进行类型检查和自动完成。（链接）

如果X-TypeScript-Types头提供的类型定义不正确，你可以通过在模块导入URL中添加?no-dts查询来禁用它：

import unescape from "https://esm.sh/lodash/unescape?no-dts";

这将阻止在网络请求中包含X-TypeScript-Types头，你可以手动为导入的模块指定类型。

支持Nodejs/Bun

Nodejs(18+)在--experimental-network-imports标志下支持http导入。Bun目前还不支持http模块。

我们强烈推荐使用Reejs作为运行时与esm.sh配合使用，它在Nodejs和Bun中都能工作。

全球CDN

<img width="150" align="right" src="https://yellow-cdn.veclightyear.com/835a84d5/60ccd11c-8981-4fd5-b297-862e2e79e47e.svg" />

esm.sh的全球CDN由Cloudflare提供，Cloudflare是世界上最大和最快的云网络平台之一。

自托管

要自行托管esm.sh，请查看托管文档。