【译】提交你的 library 到 cdnjs （2022版）

要有生产者思维。不要只当消费者，拿来主义，然后找不到就怨恨这个世界不完美。

背景

cdnjs 是优秀的开源软件 CDN 服务，大家熟知的 bootCDN 就是它的国内镜像。所以，提交到 cdnjs 之后即可通过 bootCDN 访问。

我两个多月之前发布了 wangEditor5（开源富文本编辑器），一开始使用 jsDelivr 做 CDN 服务，结果前段时间挂了。现在使用 unpkg ，隐约记得 1-2 年前它也有不稳定的时候。

所以，我想把 wangEditor5 同步到 cdnjs 。但在查找资料时没有找到中文版，或者是好几年之前过时的，于是就从 github 找到英文资料，顺便来翻译一下，供他人参考。

网上 2020 之前的方法不适用了

cdnjs 在 2 年之前做了一次提交方法的更新，所以有很多过时的资料是不适用的。

大概的意思是说：

cdnjs/cdnjs 这个仓库目前仅限于机器人操作（一些自动操作），不再受理 pull request 。如果你还想继续提交仓库到 cdnjs ，可以去看看 cdnjs/packages ，或者其他开源的仓库。

其实 cdnjs/packages 这里就有最新的提交规则，也就是本文要翻译的内容。

开始翻译

原文链接 github.com/cdnjs/packa…

文档目录

概述
政策、规则和引导
配置 lib 自动更新
- 自动更新概述
- 自动更新配置
配置文件优化
在 cdnjs 创建新 lib
- fork cdnjs 仓库
- 修改你的 fork
- 遵循已有 lib 的规则
- 使用浏览器修改
- 创建 pull request
- 修复 CI 报错
- 审查与合并

概述

cdnjs/packages 是一个 github 仓库，其中包含了很多 JSON 文件，它们控制着各个 lib 在 cdnjs.cloudflare.com 的可访问性。

cdnjs 依赖于用户提交 pull request 和自动更新的方式，来收集和更新 lib 。它包含很多贡献者和提交记录，所以通过正确的程序来提交 lib 是至关重要的。

以下两种形式的 lib 可被配置为自动更新（如何配置下文再说）

日常在 npm 上维护的
github 仓库，且有 tag 和 release 的

那些无法自动更新的 lib 将不再被 cdnjs 支持。

政策、规则和引导

cdnjs 可以托管任何生产版本的 JS 和 CSS lib，只要有合适的 license 。

cdnjs 支持常见的文件格式，如 JS, TS, CSS, SCSS, JSON, WASM, SWF, images, audio ，所有的文件格式参考这个 API api.cdnjs.com/whitelist 。

【注意】cdnjs 对新提交的 lib 有如下要求，符合一个即可：

npm 下载量 800+ 每月
github 仓库有 200+ star

配置 lib 自动更新

自动更新概述

日常在 npm 维护的包，以及在 github 有 tag release 的仓库，可以被配置为自动更新。一个 cdnjs 的脚本会定期运行（每小时一次），检查相应的 npm 包或 github release 是否有新的版本发布，并更新到 cdnjs 中。

每一个 cdnjs 都有一个 JSON 文件，其中包含了该 lib 的一些信息。自动更新就配置在这个 JSON 文件里，和其他配置信息在一起。

自动更新配置

autoupdate 一级属性，包含了所有自动更新的配置
- source 如果是 npm 包则为 npm ，如果是 git 仓库则为 git
- target npm 的名称，后者 git 仓库的 url
- fileMap 数组或者对象，告诉 cdnjs 应该拷贝哪些文件
  - basePath 要拷贝文件的根目录
  - files 要拷贝的文件名，可以直接写名字（如 lodash.min.js）也可以用 *.js 形式

PS：如果在 files 中使用通配符，请一定严格填写，不要把一些无用的文件也包含进来，避免造成浪费。

npm 包自动更新配置示例

  "autoupdate": {
    "source": "npm",
    "target": "function-plot",
    "fileMap": [
      {
        "basePath": "dist",
        "files": [
          "*.js",
          "utils/*.js"
        ]
      }
    ]
  }

示例中 function-plot 包的目录结构如下

|__dist
| |__function-plot.js
| |__utils
| | |__plotter.js
|__bower.json
|__index.js
|__site.js
|__package.json
|__README.md
|__lib
| |__...
|__node_modules
| |__...
|__sandbox
| |__...

根据配置规则，自定更新程序将定位到 dist 目录（你在 basePath 配置了），然后拷贝其中的 *.js 和 utils/*.js（你在 files 中配置了）到 cdnjs 中。再去掉 dist 目录，最终的 cdnjs 的文件目录如下

|__ajax
  |__libs
    |__function-plot
      |__x.y.z
        |__function-plot.js
        |__utils
          |__plotter.js

其中 x.y.z 是版本号，和包的 package.json 文件中版本一致。

git 仓库自动更新配置示例

  "autoupdate": {
    "source": "git",
    "target": "git://github.com/mikehostetler/amplify.git",
    "fileMap": [
      {
        "basePath": "lib",
        "files": [
          "*.js"
        ]
      }
    ]
  }

配置中的这个 git 仓库有代码结构如下

|__demo
| |__...
|__docs
| |__...
|__external
| |__...
|__lib
| |__amplify-vsdoc.js
| |__amplify.core.js
| |__amplify.core.min.js
| |__amplify.js
| |__amplify.min.js
| |__amplify.request.js
| |__amplify.request.min.js
| |__amplify.store.js
| |__amplify.store.min.js
|__src
| |__...
|__test
| |__...
|__.gitignore
|__.jshintrc
|__GPL-LICENSE.txt
|__MIT-LICENSE.txt
|__bower.json
|__build.json
|__header.js
|__package.json
|__readme.md
|__test-jquery-versions.js
|__test-server.js
|__testswarm.json

根据配置规则，自定更新程序将定位到 lib 目录（你在 basePath 配置了），然后拷贝其中的 *.js （你在 files 中配置了）到 cdnjs 中。再去掉 lib 目录，最终的 cdnjs 的文件目录如下

|__ajax
  |__libs
    |__amplify
      |__x.y.z
        |__amplify-vsdoc.js
        |__amplify.core.js
        |__amplify.core.min.js
        |__amplify.js
        |__amplify.min.js
        |__amplify.request.js
        |__amplify.request.min.js
        |__amplify.store.js
        |__amplify.store.min.js

其中 x.y.z 是版本号。

配置文件优化

默认情况下，当有新文件被自动更新进来时，cdnjs 会对特定文件进行压缩。对于 JS CSS 文件，cdnjs 会压缩代码生成 filename.min.js 和 filename.min.css 文件。对于图片文件，cdnjs 也会进行压缩处理，以节省 CDN 的带宽。

如果你想禁用这个功能，你可以通过在 JSON 文件中配置 optimization 来控制。这个配置是可选的。示例如下：

"optimization": {
    "js": false,
    "css": false,
    "png": false,
    "jpg": false
  }

在 cdnjs 创建新 lib

流程概述

Fork cdnjs/packages 仓库到你自己的 github 账户
对这个仓库进行必要的修改
提交一个 pull request 并附加合适的信息
带 PR 合并之后，删除掉你 fork 的仓库

Fork cdnjs/packages 仓库

通过 github.com/cdnjs/packa… 来 fork 仓库到你自己的 github 账号，然后你就有如下仓库了 github.com/your-github… 。

PS：请注意你 fork 的是 cdnjs/packages 而不是 cdnjs/cdnjs ，后者现在不再受理 pull reqeust

修改信息

在你 fork 的仓库中修改信息，这些信息将被提交 pull request ，最后会被 cdnjs 维护人员审查、合并。

修改信息可以通过浏览器，也可以使用 git 下载到本地…… （译者：最基本的 git 操作，这里就不说了）

译者注：
这里所说的“修改信息”，应该就是在 packages 这个仓库中，选择一个合适的文件夹（根据 lib 首字母），增加自己包的 JSON 文件，文件格式参考现有的即可，例如这个 jQuery.x18n.json 。

遵守已有 lib 的规则

当提交一个新的 lib 时，请参考已有 lib 的命名和格式，最好是参考最近新添加 lib 的 JSON 格式。

使用浏览器修改

Github 在网页上添加、修改文件还是比较方便的，很适用于这个场景。

进入你 fork 仓库的这个目录 github.com/your-github… ，再进入合适的文件夹（根据 lib 首字母），然后创建新的 JSON 文件即可。文件格式参考现有的。

创建 pull request

新增了文件之后，就可以提交 commit 并且创建 pull request 。

commit 信息要遵循如下标准格式，这样方便 cdnjs 人员来审查：
Add <lib 的名字> w/ npm/git auto-update （其中 npm/git 自己选择一个）

commit 描述是非必需的。

注意，不要提交到 master 分支，选择创建一个新分支，并取一个合适的分支名，例如 add-my-lib-name

最后创建 pull request 即可，cdnjs 的人员会尽快审核。

修复 CI 报错

为了保证提交的 JSON 文件格式的正确性，以及正确的自动更新配置，将在 PR 时自动触发 CI（github actions）。

如果 CI 检查 JSON 文件或配置错误，它讲被标记为失败。此时需要你重新修改 JSON 文件并重新提交。

审查与合并

如果 CI 检查成功，cdnjs 人员会继续人工审查 PR 内容，已确保没有任何问题。

如果人工审查没有问题，将合并这个 PR ，然后你就可以删掉之前 fork 的仓库。

感谢你对 cdnjs 的贡献。

翻译结束

最后，欢迎大家使用 wangEditor5 开源富文本编辑器。