使用文档
了解如何通过 JSDMirror 为你的项目加速静态资源
快速开始
JSDMirror 是一个免费开源的 CDN 加速服务,完全兼容 jsDelivr。你只需将现有 URL 中的域名从 cdn.jsdelivr.net 替换为 cdn.jsdmirror.com 即可完成迁移,路径规则和参数使用方式完全一致,无需改动任何业务代码。
基本用法
<!-- 引入 jQuery --> <script src="https://cdn.jsdmirror.com/npm/jquery@3.7.1/dist/jquery.min.js"></script> <!-- 引入 Bootstrap --> <link rel="stylesheet" href="https://cdn.jsdmirror.com/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"> <script src="https://cdn.jsdmirror.com/npm/bootstrap@5.3.0/dist/js/bootstrap.min.js"></script> <!-- 引入 Vue --> <script src="https://cdn.jsdmirror.com/npm/vue@3.3.4/dist/vue.global.js"></script>
URL 结构
JSDMirror 的 URL 结构简洁明了,支持多种源站类型:
| 源站类型 | URL 前缀 | 示例 |
|---|---|---|
| npm | /npm/ | /npm/jquery@3.7.1/dist/jquery.min.js |
| GitHub | /gh/ | /gh/user/repo@version/file |
| WordPress | /wp/ | /wp/plugins/akismet/tags/4.1.12/akismet.js |
| CNB | /cnb/ | /cnb/org/repo@version/file |
生产级可用
JSDMirror 已为全球数千个项目提供稳定的 CDN 加速服务,日均处理 5000 万+ 次请求,服务可用性达 99.99%。所有资源通过 HTTPS 安全传输,支持 HTTP/2。
作为 jsDelivr 的兼容替代方案,JSDMirror 在保持相同 API 接口的同时,针对中国大陆用户进行了深度优化,提供更快的访问速度和更稳定的服务质量。
多 CDN 架构
JSDMirror 基于 EdgeOne 和多家 CDN 厂商的边缘网络,在全球部署了 100+ 节点。采用智能路由技术,根据用户地理位置和网络状况自动选择最优节点。
- 智能 DNS 解析——根据用户 IP 自动调度到最近的边缘节点。
- 动态路由——实时监控节点健康状态,避开拥堵和故障节点。
- 多级缓存——浏览器 → 边缘节点 → 中间层 → 源站,四级缓存最大化命中率。
中国大陆加速
国内节点覆盖电信、联通、移动、教育网等主流运营商,确保中国大陆用户享受平均 30ms 的低延迟响应。相比海外 CDN 动辄 200ms+ 的延迟,JSDMirror 在中国大陆的访问速度有 3~5 倍的显著提升。
故障转移
JSDMirror 具备完善的故障转移机制:
- 节点故障转移——当某个边缘节点出现故障时,系统自动将流量切换到其他健康节点,对用户完全透明。
- 源站降级——当源站不可达时,继续使用缓存内容提供服务,确保业务不中断。
- 多源备份——支持配置多个回源地址,当一个源站故障时自动切换。
客户端回退 (onerror)
虽然 JSDMirror 在服务端已具备完善的故障转移和多级缓存,但在极端情况下(如 DNS 劫持、运营商拦截),CDN 资源仍可能加载失败。建议在关键资源上配置客户端 onerror 回退机制,确保页面始终可用。
以下是三种常用的客户端回退配置方式,推荐在 script 和 link 标签的 onerror 事件中设置备用 CDN 地址或本地静态资源。
方式一:内联 onerror 回退
直接在标签上使用 onerror 属性,当前地址加载失败时自动切换到备用 CDN:
<!-- 单个 script 回退 -->
<script src="https://cdn.jsdmirror.com/npm/jquery@3.7.1/dist/jquery.min.js"
onerror="this.onerror=null;this.src='https://cdn.bring.cool/npm/jquery@3.7.1/dist/jquery.min.js'">
</script>
<!-- 单个 link 回退 -->
<link rel="stylesheet" href="https://cdn.jsdmirror.com/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
onerror="this.onerror=null;this.href='https://cdn.bring.cool/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css'">方式二:全局回退脚本
配置一个全局 CDN 回退数组,通过监听 error 事件批量处理加载失败的资源:
/* 全局 CDN 回退配置 */
(function() {
var backups = {
'cdn.jsdmirror.com': 'cdn.bring.cool',
'cdn.jsdmirror.com/npm': 'cdn.bring.cool/npm',
'cdn.jsdmirror.com/gh': 'cdn.bring.cool/gh',
};
document.addEventListener('error', function(e) {
var el = e.target;
var src = (el.src || el.href || '');
if (!src) return;
for (var key in backups) {
if (src.indexOf(key) !== -1) {
var fallback = src.replace(key, backups[key]);
if (el.tagName === 'SCRIPT' && el.src) {
el.onerror = null;
el.src = fallback;
} else if (el.tagName === 'LINK' && el.href) {
el.onerror = null;
el.href = fallback;
}
break;
}
}
}, true);
})();方式三:多地址级联回退
为单个资源配置多个备用地址,按顺序尝试加载,直到某个地址成功为止:
<!-- 多地址级联回退:依次尝试 jsdmirror → bring.cool -->
<script>
(function multiFallback(tag, urls, idx) {
idx = idx || 0;
if (idx >= urls.length) {
console.error('[Fallback] 所有 CDN 地址均加载失败: ' + urls.join(', '));
return;
}
var el = document.createElement(tag === 'script' ? 'script' : 'link');
if (tag === 'script') {
el.src = urls[idx];
el.async = true;
} else {
el.rel = 'stylesheet';
el.href = urls[idx];
}
el.onerror = function() {
this.onerror = null;
this.remove();
multiFallback(tag, urls, idx + 1);
};
document.head.appendChild(el);
})('script', [
'https://cdn.jsdmirror.com/npm/jquery@3.7.1/dist/jquery.min.js',
'https://cdn.bring.cool/npm/jquery@3.7.1/dist/jquery.min.js',
]);- 备用地址优先选择同类型的 CDN(如 bring.cool、unpkg),避免回退到性能差异过大的源站
- 关键资源(如框架库、字体)建议同时配置 onerror 回退,非关键资源可不配置
- onerror 自动切换后,可以考虑通过监控上报触发告警,以便及时发现区域性问题
npm
加速任意 npm 包中的文件。
URL 格式
https://cdn.jsdmirror.com/npm/{package}@{version}/{file}| 参数 | 必需 | 说明 |
|---|---|---|
{package} | 是 | npm 包名,如 jquery、vue、lodash。支持 scoped 包如 @babel/core |
{version} | 否 | 版本号,如 3.7.1。省略则取最新版。支持 semver 范围如 ^1.0.0 |
{file} | 否 | 包内的文件路径。省略则返回默认文件(按 jsdelivr > browser > main 优先级) |
版本号用法
JSDMirror 支持多种版本号指定方式:
| 方式 | 示例 | 说明 |
|---|---|---|
| 精确版本 | jquery@3.7.1 | 指定确切版本,推荐用于生产环境 |
| 主版本 | jquery@3 | 使用 3.x 最新版本 |
| 版本范围 | jquery@3.7 | 使用 3.7.x 最新版本 |
| 最新版 | jquery | 省略版本号,始终获取最新版本 |
Scoped 包
对于 @scope/package 格式的包,将 / 替换为 / 即可:
https://cdn.jsdmirror.com/npm/@babel/core@7.23.0/lib/index.js https://cdn.jsdmirror.com/npm/@vue/runtime-dom@3.3.4/dist/runtime-dom.esm-browser.js
获取文件列表
访问包根目录(不带文件名)可以获取包内的文件结构:
https://cdn.jsdmirror.com/npm/jquery@3.7.1/ https://cdn.jsdmirror.com/npm/jquery@3.7.1/dist/
示例
<!-- 指定版本的 jQuery --> <script src="https://cdn.jsdmirror.com/npm/jquery@3.7.1/dist/jquery.min.js"></script> <!-- 最新版本的 Vue --> <script src="https://cdn.jsdmirror.com/npm/vue/dist/vue.global.js"></script> <!-- Bootstrap CSS --> <link rel="stylesheet" href="https://cdn.jsdmirror.com/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"> <!-- Scoped 包示例 --> <script src="https://cdn.jsdmirror.com/npm/@babel/standalone@7.23.0/babel.min.js"></script>
GitHub
加速 GitHub 仓库中的文件。支持按 tag、分支或 commit hash 引用。
URL 格式
https://cdn.jsdmirror.com/gh/{user}/{repo}@{branch}/{file}| 参数 | 必需 | 说明 |
|---|---|---|
{user} | 是 | GitHub 用户名或组织名 |
{repo} | 是 | 仓库名 |
{branch} | 是 | 分支名(如 main)、tag 名(如 v1.0.0)或 commit hash |
{file} | 否 | 仓库内文件路径 |
版本引用方式
| 方式 | 示例 | 说明 |
|---|---|---|
| Tag | @v5.3.0 | 推荐,引用稳定发布版本 |
| 分支 | @main | 开发测试,指向最新代码 |
| Commit | @abc1234 | 精确引用某个提交版本 |
示例
https://cdn.jsdmirror.com/gh/twbs/bootstrap@v5.3.0/dist/css/bootstrap.min.css https://cdn.jsdmirror.com/gh/jquery/jquery@main/dist/jquery.min.js https://cdn.jsdmirror.com/gh/user/repo@a1b2c3d/dist/bundle.js
以上分别演示了按 tag、分支、commit hash 三种引用方式。
WordPress
加速 WordPress 官方插件和主题目录中的文件。
URL 格式
https://cdn.jsdmirror.com/wp/plugins/{slug}/tags/{version}/{file}
https://cdn.jsdmirror.com/wp/themes/{slug}/{version}/{file}| 参数 | 必需 | 说明 |
|---|---|---|
plugins|themes | 是 | 选择插件(plugins)或主题(themes) |
{slug} | 是 | 插件或主题的 slug 标识 |
{version} | 是 | 版本号或 tags/{tag} |
{file} | 否 | 文件路径 |
示例
https://cdn.jsdmirror.com/wp/plugins/akismet/tags/4.1.12/akismet.js https://cdn.jsdmirror.com/wp/themes/twentytwenty/2.0/style.css
第一条为 Akismet 插件,第二条为 TwentyTwenty 主题。
CNB
加速 CNB 平台上的仓库文件。支持组织/子组织/仓库的层级路径,直接引用仓库中的任意文件。
URL 格式
https://cdn.jsdmirror.com/cnb/{org}/{repo}@{version}/{file}
https://cdn.jsdmirror.com/cnb/jsdmirror/jsdmirror@main/README.md| 参数 | 必需 | 说明 |
|---|---|---|
{org}/{repo} | 是 | 组织名/仓库名,如 myorg/myrepo |
{version} | 否 | 版本号,省略则取最新 |
{file} | 否 | 文件路径 |
CNB 支持按分支名、tag 名或 commit SHA 引用文件。省略版本号将使用仓库默认分支的最新版本。
多级组织路径
CNB 支持多级组织路径(如 org/sub-org/repo),路径部分直接写入 URL 即可:
https://cdn.jsdmirror.com/cnb/org/sub-org/repo@main/dist/bundle.js https://cdn.jsdmirror.com/cnb/mycompany/frontend/ui-lib@v2.0.0/index.css
更多示例
以下是更多 CNB 引用示例,涵盖不同场景:
<!-- 按分支名引用 --> https://cdn.jsdmirror.com/cnb/jsdmirror/json@main/third-party-mirrors.json <!-- 按 tag 名引用 --> https://cdn.jsdmirror.com/cnb/myorg/myrepo@v1.0.0/release/bundle.min.js <!-- 按 commit SHA 引用 --> https://cdn.jsdmirror.com/cnb/myorg/myrepo@abc123def/dist/app.js <!-- 省略版本号,使用默认分支 --> https://cdn.jsdmirror.com/cnb/myorg/myrepo/dist/app.js
Google Fonts 字体加速
JSDMirror 提供 Google Fonts 镜像加速服务,通过独立域名访问,接口与 Google Fonts 官方完全一致,可作为官方服务的备选加速方案。
URL 格式
将官方 fonts.googleapis.com 替换为 fonts.cdn.xzzo.cn 即可,路径和参数完全相同:
https://fonts.cdn.xzzo.cn/css2?family={Font}:wght@{weight}&display=swap示例
https://fonts.cdn.xzzo.cn/css2?family=Roboto:wght@400&display=swap
使用方法
在 HTML 的 <head> 中引入字体样式表,与官方用法一致:
<!-- 预连接到 CSS 和字体文件域名,加快首屏加载 -->
<link rel="preconnect" href="https://fonts.cdn.xzzo.cn">
<link rel="preconnect" href="https://font.cdn.xzzo.cn" crossorigin>
<!-- 引入 Roboto 字体 -->
<link rel="stylesheet" href="https://fonts.cdn.xzzo.cn/css2?family=Roboto:wght@400;700&display=swap">
<style>
body {
font-family: 'Roboto', sans-serif;
}
</style>Gravatar 头像加速
JSDMirror 提供 Gravatar 头像镜像加速服务,通过独立域名访问,接口与 Gravatar 官方完全一致。将邮箱地址做 SHA256 哈希后拼接 URL 即可获取头像。
URL 格式
将邮箱去除首尾空格并转小写,计算 SHA256 哈希,拼接成 URL:
https://gravatar.cdn.xzzo.cn/avatar/{sha256(email)}示例
https://gravatar.cdn.xzzo.cn/avatar/5d549030c6a922e55d14e5df541602d8053f864865da5c4a172c07d6bc9c4766
代码示例
以下示例展示如何在 JavaScript 和 PHP 中生成 Gravatar 头像 URL:
const sha256 = require('js-sha256');
function getGravatarURL(email) {
// 去除首尾空格并转小写
const address = String(email).trim().toLowerCase();
// 计算 SHA256 哈希
const hash = sha256(address);
// 拼接头像 URL
return `https://gravatar.cdn.xzzo.cn/avatar/${hash}`;
}<?php
function get_gravatar_url($email) {
// 去除首尾空格并转小写
$address = strtolower(trim($email));
// 计算 SHA256 哈希
$hash = hash('sha256', $address);
// 拼接头像 URL
return 'https://gravatar.cdn.xzzo.cn/avatar/' . $hash;
}合并多个文件
JSDMirror 支持将同一源站下的多个文件合并为一个请求返回,有效减少 HTTP 请求数,提升页面加载性能。
URL 格式
https://cdn.jsdmirror.com/combine/{source}/{package}@{version}/{file1},{source}/{package}@{version}/{file2}示例
https://cdn.jsdmirror.com/combine/npm/jquery@3.7.1/dist/jquery.min.js,npm/bootstrap@5.3.0/dist/js/bootstrap.min.js https://cdn.jsdmirror.com/combine/gh/user/repo@main/a.js,gh/user/repo@main/b.js
第一条为合并两个 npm 包,第二条为合并两个 GitHub 文件。
缓存策略
JSDMirror 采用多级缓存策略,确保资源加载速度和新鲜度的最佳平衡:
- 浏览器缓存——带版本号的资源默认缓存 1 年,通过 Cache-Control: public, max-age=31536000, immutable 响应头控制。版本不变内容不变,可以放心长期缓存。
- CDN 边缘缓存——热门资源长期缓存在 100+ 边缘节点,首次加载后极速命中。
- CDN 中间层缓存——回源请求缓存于 CDN 中间层,减少源站压力,提高回源速度。
- 源站缓存——最终回源到 npm/GitHub 等上游,正常情况极少触发。
版本化资源(推荐)
当你使用带有精确版本号的 URL(如 jquery@3.7.1)时,该资源被视为不可变的,CDN 会永久缓存。这是强烈推荐的生产环境最佳实践。
无版本 / 范围版本资源
使用不带版本号(如 jquery)、主版本(如 jquery@3)或版本范围(如 jquery@^3.0.0)时,CDN 缓存时间为 12 小时。系统检测到新版本发布后会逐步更新缓存。
| URL 类型 | 缓存时间 | 何时更新 |
|---|---|---|
jquery@3.7.1 | 1 年 | 永不变更(内容不可变) |
jquery@3 | 12 小时 | 检测到新的 3.x 版本时 |
jquery | 12 小时 | 检测到任何新版本时 |
刷新缓存
如果你需要立即更新某个资源的 CDN 缓存,可以使用以下方式:
- 访问 https://eo.xzzo.cn/cache/
- 输入需要刷新的完整 URL
- 提交刷新请求,通常 1 分钟内 完成
API 接口
包元数据
获取 npm 包的版本信息和元数据:
https://cdn.jsdmirror.com/npm/jquery@3.7.1/package.json https://cdn.jsdmirror.com/npm/jquery/
获取包信息(JSON 格式);获取包的所有可用版本
统计接口
| 方法 | 端点 | 说明 |
|---|---|---|
| GET | https://status.jsdmirror.com/ | 查询服务流量统计与运行状态 |
缓存刷新接口
| 方法 | 端点 | 说明 |
|---|---|---|
| POST | https://eo.xzzo.cn/cache/ | 提交缓存刷新请求 |
速率限制
为保证所有用户的服务质量,JSDMirror 实行以下速率限制:
| 套餐 | 单线程限速 | 单 IP QPS | 月流量 |
|---|---|---|---|
| 免费版 | 500 KB/s(前3秒不限) | 300 | 100 GB |
| 个人版 | 2 MB/s(前3秒不限) | 1,000 | 1 TB |
| 定制套餐 | 可定制 | 不限 | 不限 |
软件包作者最佳实践
所有托管在 npm 上的包和 GitHub 上标记的发布包都会自动在 JSDMirror 上提供。如果你是软件包作者,以下是一些让使用软件包尽可能简单的建议:
- 使用 SemVer 进行版本控制(这由 npm 强制执行,但 GitHub 不强制执行)。
- 如果列表中的文件不适合浏览器使用,请在 package.json 中设置 browser 或 jsdelivr 字段。
- 如果你分发的是压缩后的 JS/CSS 文件,也要包含这些文件的源码映射(source maps)。
- 如果你不想提供压缩文件,也没关系——我们会帮你处理。
- 在 package.json 中配置默认文件。
默认文件配置
对于托管在 npm 上的包,JSDMirror 支持提供带有较短 URL 的"默认"文件。默认文件可以通过在 package.json 中设置以下字段之一进行配置,优先级从高到低:
| 优先级 | 字段 | 说明 |
|---|---|---|
| 1(最高) | jsdelivr | jsdelivr 专用字段,拥有最高优先级,JSDMirror 会遵守这个规则 |
| 2 | browser | 浏览器环境入口文件 |
| 3 | main | 通用入口文件 |
JSDMirror 会首先尝试查找对应文件的压缩版本(移除 .js 扩展名并查找 .min.js)。如果找不到压缩版本,则会提供原始文件。
同时包含 JS 和 CSS 的项目
对于既有 JS 文件又包含 CSS 文件的项目,请使用上述字段作为 JS 入口文件,使用 style 字段指定 CSS 文件。
{
"name": "my-library",
"version": "1.0.0",
"jsdelivr": "./dist/my-library.min.js",
"style": "./dist/my-library.min.css"
}限制说明
为保证服务质量,JSDMirror 对单个资源和包大小有限制:
- 单个包的总大小不得超过 150 MB。
- 单个文件(以 GitHub 为例)不得超过 20 MB。
我们建议尽可能从包中移除不需要的文件以减小体积。如果你需要为包裹设置更高的限额,请在 GitHub 仓库中开启 Issue。
自定义 CDN 托管
我们可以合作,为你的项目设置自定义配置。这样,你可以完全控制你的文件,并充分利用 JSDMirror 的全部功能。
适用场景
- 二进制托管——Windows 可执行文件和压缩包。
- 文件频繁更新——需要实时同步的场景。
- 特殊文件结构——无法遵循 JSDMirror 标准文件结构的项目。
- 以及更多让我们大开眼界的用途。
子资源完整性(SRI)
确保从 JSDMirror 加载的资源未被篡改
什么是 SRI?
子资源完整性(Subresource Integrity,SRI)是一种安全特性,允许浏览器在获取资源时验证其完整性。通过对比文件的实际加密哈希值与你在 integrity 属性中提供的期望哈希值,浏览器能够判断文件是否被篡改。
SRI 如何工作
当你从 CDN 加载第三方脚本或样式时,你实际上是在信任该 CDN 的安全性和稳定性。但如果 CDN 被攻陷、文件被恶意替换,攻击者就能在你的网站上执行任意代码。
SRI 通过在 HTML 标签上添加 integrity 属性来规避这一风险。该属性包含一个或多个文件的加密哈希值。浏览器在加载资源后,会计算该文件的实际哈希值,并与 integrity 中的值进行比对:
- 哈希匹配 → 资源正常加载执行
- 哈希不匹配 → 浏览器拒绝执行,返回网络错误
如何使用 SRI
在 <script> 或 <link> 标签上添加 integrity 和 crossorigin 属性。
integrity 属性的格式
属性值格式为 "算法-哈希值",支持同时提供多个空格分隔的哈希值(文件只需匹配其中一个即可通过验证):
integrity="sha384-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
支持的哈希算法:
- sha256 — 256 位 SHA-2 哈希,Base64 编码
- sha384 — 384 位 SHA-2 哈希,Base64 编码(推荐)
- sha512 — 512 位 SHA-2 哈希,Base64 编码
生成 SRI 哈希值
命令行生成
使用 OpenSSL(推荐,跨平台):
cat FILENAME.js | openssl dgst -sha384 -binary | openssl base64 -A
使用 shasum(macOS / Linux):
shasum -b -a 384 FILENAME.js | awk '{ print $1 }' | xxd -r -p | base64Windows 批处理脚本:
@echo off set bits=384 openssl dgst -sha%bits% -binary %1% | openssl base64 -A > tmp set /p a= < tmp del tmp echo sha%bits%-%a% pause
保存为 sri-hash.bat,右键文件 → 发送到 → 该脚本即可输出哈希值。
跨源资源共享 (CORS) 与 SRI
对于从不同域(即跨源)加载的资源,SRI 验证要求浏览器同时进行 CORS 检查。服务器必须在响应头中包含 Access-Control-Allow-Origin(或指定你的域名),且你必须在标签上设置 crossorigin="anonymous"。
如果服务器未返回正确的 CORS 响应头,即使哈希值完全匹配,浏览器也会拒绝加载该资源。
JSDMirror 所有资源默认已配置 Access-Control-Allow-Origin: *,你只需在标签上添加 crossorigin="anonymous" 即可。
JS 文件示例
<script src="https://cdn.jsdmirror.com/npm/jquery@3.7.1/dist/jquery.min.js" integrity="sha512-v2CJ7UaYy4JwqLDIrZUI/4hqeoQieOmAZNXBeQyjo21dadnwR+8ZaIJVT8EE2iyI61OV8e6M8PP2/4hpQINQ/g==" crossorigin="anonymous"> </script>
CSS 文件示例
<link rel="stylesheet" href="https://cdn.jsdmirror.com/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" integrity="sha512-jnSuA4Ss2PkkikSOLtYs8BlYIeeIK1h99ty4YfvRPAlzr377vr3CXDb7sb7eEEBYjDtcYj+AjBH3FLv5uSJuXg==" crossorigin="anonymous">
多哈希值示例
可以同时指定多个哈希值(跨浏览器或未来升级时提供兼容性),文件只需匹配其中任意一个即可通过校验:
<script src="https://cdn.jsdmirror.com/npm/lodash@4.17.21/lodash.min.js" integrity="sha384-M6AVYaH6du1M4aPFfoO9lfZxjGbksZf5X0U4Y6L+ZxgZh8Bj8TsNhqgIz6qSPbw sha512-F7IzMNt3cX/jKpJOBaVWyOQZrF2Yy5L3y7LqR+uGW8bPqCwnCsxHX9kRr3jDF/HkBHCeQQ5VgSYVjXZQbbKVw==" crossorigin="anonymous"> </script>
浏览器如何处理 SRI
- 浏览器发起资源请求,获取文件内容
- 计算文件内容的加密哈希值
- 与 integrity 属性中的期望哈希值比对
- 若不匹配 → 拒绝执行脚本 / 应用样式,并发送网络错误到控制台
- 若跨源资源 → 额外检查 CORS 响应头
- 全部校验通过 → 正常加载并执行
请注意:integrity 属性的值需要根据你实际资源的哈希值生成,不同的文件内容哈希值完全不同。
JSDMirror 响应头一览
| 参数 | 说明 |
|---|---|
x-jsd-version | JSDMirror 软件版本号,记录当前运行的镜像版本 |
x-jsd-version-type | 版本类型(version 精确版本 / alias 别名引用等) |
version | HTTP 协议版本(HTTP/2.0 或 HTTP/1.1),由客户端和服务端协商决定 |
date | 服务器响应的 UTC 时间,用于判断资源新鲜度 |
content-type | 响应内容类型,比如 application/javascript 表示 JS 文件,text/css 表示样式文件 |
content-encoding | 内容压缩方式,通常是 gzip 或 br,浏览器会自动解压 |
content-length | 响应体字节大小,方便客户端确认接收完成 |
accept-ranges | 支持断点续传,大文件下载不会断掉重来 |
etag | 资源指纹,浏览器下次请求可带 If-None-Match 校验是否有更新,304 就不重新下载 |
vary | 告诉中间缓存按什么维度区分,比如按 Accept-Encoding 区分压缩版本 |
cache-control | 浏览器缓存策略,告诉浏览器该缓存多久、过期了 stale-while-revalidate 还能用多久 |
x-ser | 服务端节点编号,用于排查请求走了哪些服务器 |
eo-cache-status | EdgeOne 缓存命中状态(HIT 命中 / MISS 回源) |
eo-log-uuid | EdgeOne 请求追踪 ID,排查问题时用 |
access-control-allow-origin | CORS 跨域策略,* 表示允许任意域名引用资源 |
access-control-allow-methods | 跨域允许的 HTTP 方法,* 表示 GET、POST、HEAD 等全部放行 |
access-control-expose-headers | 允许客户端 JS 读取哪些响应头,* 即全部可读 |
access-control-max-age | CORS 预检请求结果的缓存时间(秒),减少不必要的 OPTIONS 请求 |
cross-origin-resource-policy | 跨域资源策略,cross-origin 表示允许被任何页面引用嵌入 |
timing-allow-origin | 允许跨域页面获取资源的性能数据(Resource Timing API) |
x-content-type-options | nosniff 告诉浏览器别猜 MIME 类型,服务器声明什么就是什么,防 MIME 混淆注入 |
strict-transport-security | HSTS,告诉浏览器在未来一段时间内只走 HTTPS,杜绝 SSL 降级攻击 |
x-request-info | 请求摘要信息,包含客户端 UA 等上下文,调试用 |
x-authority | 请求权威信息,通常为空 |
referer | 请求来源页地址,通常为空(CDN 资源一般没有来源页) |
nel、report-to | 网络错误日志与上报端点,帮我们实时监控全球服务质量 |
server | 服务器名称 |
cdn | CDN 供应商名称 |
x-served-by | 服务商标识 |
x-client-ip | 客户端 IP 地址 |
x-client-city | 客户端所在城市 |
x-client-country | 客户端所在国家 |
x-client-continent | 客户端所在大洲 |
x-client-port | 客户端端口 |
requestsource | 请求来源标识 |
x-ua | 客户端 User-Agent |
x-platform | 客户端平台 |
x-request-uri | 请求完整地址 |
反向代理说明
如果你用 Nginx、Caddy 之类反代工具绑了自己的域名来做 JSDMirror 镜像,有个小坑需要留意——上游会返回一些源站的响应头,这些头如果不清理掉,镜像可能就没法正常用了。倒不是什么大问题,照着下面删掉就行。
⚠ 需要清理的响应头(12 个)
server、cdn、x-served-by、x-client-ip、x-client-city、x-client-country、x-client-continent、x-client-port、requestsource、x-ua、x-platform、x-request-uri为什么会有这个问题
不是什么 bug,是我们后端自己做的一道安全检查。后端看到请求来自一个"JSDMirror 镜像",但响应里又带着上面这些源站的标识头,会觉得不太对劲——来源看起来像镜像,特征又像官方源,前后对不上。出于安全考量,这种情况下会直接把请求跳回官方源。
不清理会怎样
镜像就返回不了内容,直接跳到官方源了。说白了就是我们目前还没办法判断:你这个第三方反代站,到底有没有改过加速内容?在搞清楚之前,宁可保守一点先跳走。不是说你的站有问题,纯粹是我们自己这块还没做到位,先稳妥处理。
Nginx 配置示例
# 把这部分加到你的 location 块里就搞定了
location / {
proxy_pass https://cdn.jsdmirror.com;
# 需要清理的响应头,防止被后端安全策略拦截
proxy_hide_header server;
proxy_hide_header cdn;
proxy_hide_header x-served-by;
proxy_hide_header x-client-ip;
proxy_hide_header x-client-city;
proxy_hide_header x-client-country;
proxy_hide_header x-client-continent;
proxy_hide_header x-client-port;
proxy_hide_header requestsource;
proxy_hide_header x-ua;
proxy_hide_header x-platform;
proxy_hide_header x-request-uri;
# 下面这些顺手也去了吧,少暴露一点来源信息
proxy_hide_header x-cache;
proxy_hide_header x-cache-hits;
proxy_hide_header via;
}第三方 jsDelivr 镜像推荐
以下是由社区维护的 jsDelivr 第三方镜像站点,可作为备用或替代方案。这些站点由第三方独立运营,JSDMirror 官方不对其稳定性和安全性负责,使用前请自行评估。
推荐站点
| 站点域名 | 运营者 | CDN 提供商 | 区域 | 支持大陆 | 简介 |
|---|---|---|---|---|---|
| 正在加载镜像列表... | |||||
他们也在使用 JSDMirror
自 JSDMirror 上线以来,越来越多的开发者和团队选择将他们的项目托管在我们提供的 CDN 加速服务上。从前端框架、UI 组件库、图标集,到 WordPress 主题、Typecho 插件、Hexo 博客模板,再到各类开源工具和商业 SaaS 产品——JSDMirror 的身影已经遍布互联网的各个角落。
我们始终相信,开源社区的力量在于分享与连接。每一次资源的加速分发,每一个项目的顺利上线,背后都凝聚着无数开发者的信任与托付。这份信任,是我们持续优化节点、提升可用性、拓展覆盖范围的最大动力。
在此刻,我们许下几个小小的祈愿:希望越来越多的开发者愿意将项目托付给 JSDMirror,彼此信任、互相成就;希望听到更多来自一线的使用反馈,无论是建议、吐槽还是脑洞,都是我们改进的方向;希望这份上墙名单越来越长,我们也支持随时上下架——通过 CNB Issue 或发送邮件均可,想上就上、想下就下,让每一个使用 JSDMirror 的项目都能被看见,彼此见证、共同前行。
如果你正在使用 JSDMirror,无论你的项目是大是小、是商业是开源,我们都欢迎你在此留下足迹。你的每一次使用,都是对 JSDMirror 最好的肯定。
Cookie 与数据使用说明
为了提供更好的使用体验,我们会在你的浏览器中存储少量必要数据,包括主题色偏好、深色/浅色模式选择以及界面语言。这些数据仅用于记住你的偏好设置,不包含任何个人身份信息,也不会被用于跟踪、广告或商业目的。如果你在底部的 Cookie 提示栏中点击"我不同意",所有偏好将不会被保存,每次访问都需重新配置;点击"我知道了"则会将上述设置保存在你的浏览器中,下次打开时自动恢复。
数据收集明细
以下是我们会在你浏览器中存储的全部数据,每一项都写明了用途:
| 存储键名 | 存储位置 | 数据类型 | 用途说明 |
|---|---|---|---|
jsdmirror_color | Cookie | 颜色哈希值(如 #3b82f6) | 记录你选择的主题色偏好。当你下次打开网站时,页面会直接加载你上次选择的颜色,无需重新设置。该 Cookie 仅存储一个颜色值,不包含任何个人身份信息。 |
theme | Cookie | 字符串(light / dark) | 记录你选择的主题模式偏好(浅色模式或深色模式)。页面加载时会从 Cookie 读取并应用对应主题,让你无需每次手动切换。该值仅表示"亮/暗"两种状态,无任何追踪能力。 |
lang | Cookie | 语言代码(如 zh、en) | 记录你选择的界面语言。当我们有多语言内容时,会优先使用你选择的语言显示页面,Cookie 同时也供服务端读取。 |
jsdmirror_cookie_consent | LocalStorage | 字符串(1 或 0) | 记录你是否同意我们使用上述偏好存储。"1" 表示你已知晓并同意,"0" 表示你不希望我们记录任何偏好。如果你选择"我不同意",我们将不会存储任何颜色、主题或语言偏好,你的选择每次都需要重新设置。 |
访问分析与性能监控
为了持续改善服务质量,我们会通过 NEL(Network Error Logging)和 Report-To 机制收集匿名化的网络请求性能数据,包括但不限于:资源加载成功率、请求延迟分布、CDN 缓存命中率等。这些数据不包含任何用户标识,仅用于监控全球边缘节点的健康状态和优化加速策略。
第三方服务
我们的 CDN 加速服务基于腾讯云 EdgeOne 提供。EdgeOne 在其边缘节点处理请求时会记录必要的访问日志(如请求 URL、响应状态码、客户端 IP 的地理位置归属),这些日志用于安全防护(如 DDoS 防御、CC 攻击检测)和服务质量分析,符合腾讯云数据合规要求。除此之外,我们不会主动将你的任何数据分享给其他第三方。
你的控制权
- 当你在我们网站底部的 Cookie 提示栏中点击"我不同意"后,所有偏好设置都将被清除且不再记录。此后你每次改变主题色、主题模式或语言设置时,页面刷新后均不会保留。
- 你也可以随时通过浏览器开发者工具清除本站的 Cookie 和 LocalStorage 数据,来手动移除所有已存储的偏好信息。
- 如需了解更多信息或有任何隐私方面的疑问,欢迎随时联系 ayao@cola.email。