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
esm.sh的全球CDN由Cloudflare提供,Cloudflare是世界上最大和最快的云网络平台之一。
自托管
要自行托管esm.sh,请查看托管文档。