# @adobe/ccweb-add-on-devcert 中文文档

规范地址：https://npmcn.com/package/%40adobe/ccweb-add-on-devcert/

版本：0\.2\.2
npm 元数据更新时间：2026-10-01T01:32:34.159Z
中文译文更新时间：2026-11-06T02:28:52.266Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40adobe/ccweb-add-on-devcert
原文对照：https://npmcn.com/package/%40adobe/ccweb-add-on-devcert/?lang=original
项目主页：https://github.com/adobe/ccweb-add-on-devcert#readme
源码仓库：https://github.com/adobe/ccweb-add-on-devcert

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：247 kB，46 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：23 个
- 首次发布：2023-10-04T03:34:03.199Z
- 最新版本发布：2025-06-27T06:40:59.617Z
- 近 30 天下载量：6410（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 0 个）

## 中文简介

为本地 SSL 开发生成可信任的本地 SSL/ TLS 证书

## 安装

```sh
npm install @adobe/ccweb-add-on-devcert
```

也可以使用：`pnpm add @adobe/ccweb-add-on-devcert`、`yarn add @adobe/ccweb-add-on-devcert`、`bun add @adobe/ccweb-add-on-devcert`

## README

> \[注\]  
> 这是叉子 [解析器](https://github.com/davewasmer/devcert) \[版权戴夫·瓦斯默\]. 它在已经提供的出色能力之外增加了以下能力: **解析器**数字 :
> 
> -   撤销已有的 **解析器** 为一个域创建 SSL 证书 。 目前,只有SSL资产在 `devcert.removeDomain(DOMAIN_NAME)` 名为. 在此更改后, SSL 证书首先被取消, 然后被移除 .

# devcert - 开发 SSL 方便

所以,运行本地的HTTPS服务器通常很烂. 有范围 每一个方法都有各自的取舍。 普通的,使用自签名 证书,意味着必须忽略每个工程的恐怖浏览器警告.

devcert使过程变得简单. 要私钥和证书文件到 用你的服务器吗? 只是问:

```js
let ssl = await devcert.certificateFor("my-app.test");
https.createServer(ssl, app).listen(3000);
```

现在打开 https://my-app. test: 3: 00 和 voila - 您的页面负载没有恐惧 警告或敲门.

> 证书是按名称缓存的, 所以需要两次 `certificateFor('foo')` 将返回相同的密钥和证书.

## 选项

当安装或升级时, devcert 创建自签名证书 用于签署其创建的所有证书的权威。 它会尝试 以 OSX 、 Linux 和 Windows 的 OS 键链注册此 CA 。 不过, 一些HTTP客户端(如Firefox和NodeJS本身)使用自己信任的 证书列表而不是操作系统的密钥链 。 这个 `getCaPath` 财务报告和审定财务报表 `getCaBuffer` 选项 `certificateFor()` 返回对象本身,以便这些程序可以选择是否信任它.

### 获取CaPath

设定此选项为 `true` 返回对象将包含一个 `caPath` 属性,设置为证书权威文件的文件路径。 使用这个 路径,将证书添加到本地信任商店中,接受路径为 参数, 如 NodeJS 的内建环境变量 `NODE_EXTRA_CA_CERTS`.

### 获取缓冲

设定此选项为 `true` 返回对象将包含一个 `ca` 属性,设置为证书权威的UTF-8编码内容 文档。 使用此路径将证书添加到本地信任仓库中, 而非 使用 OS 设置, 使用上述示例.

### 跳过HostsFile

如果您提供自定义域名(即除此之外的任何域名) `localhost`(中文(简体) ) 当请求 devcert 证书时, 它会尝试修改您 系统可以将域名请求重定向到本地机器(而不是 而不是真实域). 它通过修改你的 `/etc/hosts` 文档.

如果你通过 `skipHostsFile` 选项,devcert将跳过此步骤。 这个 表示如果您需要证书 `my-app.test` (例如),和 没有其他的 DNS 重定向方法, 你将无法 访问您的应用程序 : `https://my-app.test` 因为你的电脑不知道 那个 `my-app.test` 应该解决你的本地机器.

记住 SSL 证书是为 _域_所以,如果你问 证书 `my-app.test`,没有DNS重定向 到位`/etc/hosts` 试图打击 `localhost` 没用的, 即使你打算通过 `my-app.test` 正在运行在您的 本地机器( 因为 SSL 证书不会说) `localhost`) (中文(简体) ).

### 跳过Certutil

此选项会告诉 devcert 避免安装 `certutil` 用于工具.

`certutil` 是用于自动安装SSL的工具包 在某些情况下的证书; 特别是 Firefox(每个操作系统) 和克罗姆(只见Linux).

通常情况下, devcert 会尝试安装 `certutil` 如果需要的话 不需要的话 已经出现在你的系统。 如果不想让 devcert 安装这个 软件包,通过 `skipCertutil: true`。 。 。 .

如果你决定 `skipCertutil`, devcert 初始设置进程 这两种情况的变化:

-   **所有平台上的火狐**:谢了,Firefox使这个容易. 有一个 用于导入和信任证书的点和单击向导, 因此如果您 指定 `skipCertutil: true`,devcert将自动打开 Firefox 踢出这个巫师为你。 只要遵守命令,相信 证书. **提醒:每台机器只需一次**
    
-   **Linux 上的颜色**:不幸的是,似乎 **仅限** 如何获得 在 Linux 上信任 SSL 证书的 Chrome 是通过 `certutil` 工具设置 - 没有手工程序。 因此,如果你在 Linux 上使用 Chrome, 请 **没有** 供应 `skipCertuil: true`。如果选中的话, devcert 证书将不会 被克罗姆信任.
    

这个 `certutil` 以OS特定方式安装工具:

-   麦克: `brew install nss`
-   林纳: `apt install libnss3-tools`
-   Windows:N/A(在Windows上安装Certutil没有容易的手动方式, 因此, evcert 将简单地回落到 Firefox 的向导方法 上文)

## 多个域( SAN)

如果您正在开发一个多租户的应用程序, 或者在本地拥有许多应用程序, 您可以生成一个安全性 证书使用 `devcert` 同时使用 [主题替代名称](https://en.wikipedia.org/wiki/Subject_Alternative_Name) 扩展名,只需通过一系列域即可.

```js
let ssl = await devcert.certificateFor([
    "localhost",
    "local.api.example.com",
    "local.example.com",
    "local.auth.example.com",
]);
https.createServer(ssl, app).listen(3000);
```

## Docker和当地发展

如果您正在和 Docker 一起开发, 一个选项是安装 `devcert` 输入您主目录中的基础文件夹,并 为本地的 Docker 项目创建证书。 见以下各节的评论和说明: [这个问题](https://github.com/davewasmer/devcert/issues/17)。 。 。 .

虽然不优雅,但你只需要在本地增加新域时经常这样做,这很可能并不经常.

总的剧本看起来很像:

```js
// example: make a directory in home directory such as ~/devcert-util
// ~/devcert-util/generate.js
const fs = require("fs");
const devcert = require("devcert");

// or if its just one domain - devcert.certificateFor('local.example.com')
devcert
    .certificateFor(["localhost", "local.api.example.com", "local.example.com", "local.auth.example.com"])
    .then(({ key, cert }) => {
        fs.writeFileSync("./certs/tls.key", key);
        fs.writeFileSync("./certs/tls.cert", cert);
    })
    .catch(console.error);
```

使用以上脚本生成的文件的简单方法是复制 `~/devcert-util/certs` 文件夹进入您的 Docker 项目 :

```
# local-docker-project-root/
🗀 certs/
  🗎 tls.key
  🗎 tls.cert
```

把这个行添加到您的 `.gitignore`数字 :

```
certs/
```

这两个文件现在可以很容易地被任何项目使用,无论是Node.js还是别的什么.

在节点中, 在 Docker 内部, 只需将复制的证书文件载入您的 https 服务器 :

```js
const fs = require("fs");
const Express = require("express");
const app = new Express();
https
    .createServer(
        {
            key: fs.readFileSync("./certs/tls.key"),
            cert: fs.readFileSync("./certs/tls.cert"),
        },
        app
    )
    .listen(3000);
```

与 Webpack dev 服务器或类似技术合作:

```js
// webpack.config.js
const fs = require("fs");

module.exports = {
    //...
    devServer: {
        contentBase: join(__dirname, "dist"),
        host: "0.0.0.0",
        public: "local.api.example.com",
        port: 3000,
        publicPath: "/",
        https: {
            key: fs.readFileSync("./certs/tls.key"),
            cert: fs.readFileSync("./certs/tls.cert"),
        },
    },
};
```

## 如何运作

当你要求开发证书时, devcert 将首先检查查看 如果它曾经运行在这个机器上。 如果没有,它就会产生根 证书权限并添加到您的操作系统以及各种浏览器信任商店中 . 此时您可能会看到您的操作系统发出的密码提示来授权 新的根 CA.

既然你的机器现在信任这个根 CA, 它会信任任何证书 由它签署。 所以,当您要求证书 一个新域, devcert 将使用 root CA 证书生成针对 域,然后返回新证书.

如果您请求一个已经为此生成证书的域, devcert 将简单的返回缓存证书 .

此设置可确保浏览器不会显示关于不信任的恐怖警告 证书,因为您的 OS 和浏览器现在将信任 devcert 的 证书.

## 安全问题

您的操作系统在 devcert 时提示您获取根密码是有原因的 尝试安装它为根证书权威 。 把它加进你的 机器的信托商店,您的浏览器会自动信任 _任意_ 证书 用它创造的.

这暴露了您本地机器上潜在的攻击矢量:如果有人 可使用devcert证书权限生成证书,如果 他们可以拦截/操纵你的网络流量,理论上可以 冒充一些网站,您的浏览器不会显示任何警告( 因为 它信任神权.

为了防止这种情况,devcert采取步骤,确保无人能够进入 devcert 证书权威证书生成恶意证书 却不知道 具体方法因平台而异:

-   **macOS 和 Linux**:证书管理机关的证书被写到只有根用户(即:. `chown 0 ca-cert.crt` 财务报告和审定财务报表 `chmod 600 ca-cert.crt`) (中文(简体) ). 当Devcert本身需要这些时,它就会弹出到 `sudo` 援引阅读/写全权证书.
-   **窗口**: 由于我对Windows文件权限不熟悉,我 我不确定自己能正确设置 来模仿设定 在macOS和Linux上。 因此,devcert会提示你一个密码,然后 用AES256密码加密证书 密码永远不会 写入磁盘.

为了进一步保护这些证书,每当它们被写到磁盘上,它们就 被写入临时文件,并在不再需要后立即被删除.

此外,根 CA 证书只对您的机器是独有的: 首次安装时生成于飞行上。 确保没有 中央/共享密钥可以突破机器.

### 为什么要安装根证书权限 ?

根证书权限使得管理哪个域更为简单 由 devcert 为 SSL 配置 。 另一种方法是产生和信任 每个域的自签名证书。 问题是,虽然 devcert 可以在您的机器的信托商店中添加证书,工具 删除证书并不涵盖每个案件。 所以,如果你曾经想 _不信任_ devcert的证书,你必须手动移除每个从 每个信托店.

通过只信任一个根 CA,devcert能够保证 当你 想要吗 _禁用_ 一个域的 SSL, 它不用手工干预就可以做到这一点

-   我们只是删除特定域证书文件。 自从这些 指定域的文件一旦安装在您的信任仓库中 他们不见了.

## 一体化

devcert 从第一天开始就设计成低等库 工具可以委托给。 目标是让HTTPS的发展对每个人来说都比较容易, 不论框架或库的选择.

考虑到这一点,如果你想在你的图书馆/框架/CLI中使用编译器, 脱口秀使这容易.

除了上述选项外,devcert还披露a `ui` 选项。 此选项 允许您控制 devcert 重新对用户交互的所有点, 替换您自己的提示和用户界面。 你可以用这个来打牌 使用您自己的工具名称的经验,将信件本地化,或集成 切入更大的现有工作流程.

这个 `ui` 选项应为对象,其方法如下:

```ts
{
  async getWindowsEncryptionPassword(): Promise<string> {
    // Invoked when devcert needs the password used to encrypt the root
    // certificate authority credentials on Windows. May be invoked multiple
    // times if the user's supplied password is incorrect
  },
  async warnChromeOnLinuxWithoutCertutil(): Promise<string> {
    // Invoked when devcert is run on Linux, detects that Chrome is installed,
    // and the `skipCertutil` option is `true`. Used to warn the user that
    // Chrome will not work with `skipCertutil: true` on Linux.
  },
  async closeFirefoxBeforeContinuing() {
    // Invoked when devcert detects that Firefox is running while it is trying
    // to programmatically install it's certificate authority in the Firefox
    // trust store. Firefox appears to overwrite changes to the trust store on
    // exit, so Firefox must be closed before devcert can continue. devcert will
    // wait for Firefox to exit - this is just to prompt the user that they
    // need to close the application.
  },
  async startFirefoxWizard(certificateHost: string) {
    // Invoked when devcert detects a Firefox installation and `skipCertutil:
    // true` was specified. This is invoked right before devcert launches the
    // Firefox certificate import wizard GUI. Used to give the user a heads up
    // as to why they are about to see Firefox pop up.
    //
    // The certificateHost provided is the URL for the temporary server that
    // devcert has spun up in order to trigger the wizard(Firefox needs try to
    // "download" the cert to trigger the wizard). This URL will load the page
    // supplied in the `firefoxWizardPromptPage()` method below.
    //
    // Normally, devcert will automatically open this URL, but in case it fails
    // you may want to print it out to the console with an explanatory message
    // so the user isn't left hanging wondering what's happening.
  },
  async firefoxWizardPromptPage(certificateURL: string): Promise<string> {
    // When devcert starts the Firefox certificate installation wizard GUI, it
    // first loads an HTML page in Firefox. The template used for that page is
    // the return value of this method. The supplied certificateURL is the path
    // to the actual certificate. The Firefox tab must attempt to load this URL
    // to trigger the wizard.
    //
    // The default implemenation is a simple redirect to that URL. But you could
    // supply your own branded template here, with a button that says "Install
    // certificate" that is linked to the certificateURL, along with a more in
    // depth explanation of what is happening for example.
  }
  async waitForFirefoxWizard() {
    // Invoked _after_ the Firefox certificate import wizard is kicked off. This
    // method should not resolve until the user indicates that the wizard is
    // complete (unfortunately, we have no way of determining that
    // programmatically)
  }
}
```

你可以提供任何或所有的方法 - 不提供的方法会下降 回到默认执行.

## 测试

测试像德克特这样的工具可能是一种痛苦. 我还没有找到一个很好的自动 跨平台 GUI 测试的解决方案( GUI 部分是测试所必需的) 每个浏览器处理 devcert 证书, 以及测试 Firefox 向导流).

为了让事情变得更容易,devcert会带来一系列虚拟机器图像. 每个都是在测试前拍的快照 发射机器然后击中.

您也可以使用缩放的 VMs 状态将其卷回 纯正状态再试一轮.

> **说明**:请注意macOS许可条款禁止运行它 非苹果硬件 所以你必须拥有一个Mac来测试该平台. 如果你没有 拥有一个Mac - 这没关系, 只是在公关上提及 你无法测试 我们很乐意为你测试一下.

### 虚拟机器快照

-   [马科斯](https://s3-us-west-1.amazonaws.com/devcert-test-snapshots/macOS.pvm.zip)
-   [窗口](https://s3-us-west-1.amazonaws.com/devcert-test-snapshots/MSEdge+-+Win10.zip)
-   [乌邦图](https://s3-us-west-1.amazonaws.com/devcert-test-snapshots/Ubuntu+Linux.zip)

## 许可证

麻省理工学院 [戴夫·瓦斯默](http://davewasmer.com/)

## 常见问题

### @adobe/ccweb-add-on-devcert 是什么？

为本地 SSL 开发生成可信任的本地 SSL/ TLS 证书

### 如何安装 @adobe/ccweb-add-on-devcert？

在项目目录运行 npm install @adobe/ccweb-add-on-devcert，或使用 pnpm add / yarn add / bun add。

### @adobe/ccweb-add-on-devcert 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @adobe/ccweb-add-on-devcert 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adobe/ccweb-add-on-devcert 可以商用吗？

@adobe/ccweb-add-on-devcert 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @adobe/ccweb-add-on-devcert 的下载量有多少？

根据 npm 官方下载统计，@adobe/ccweb-add-on-devcert 在 2026/10/05 – 2026/11/03 这 30 天内被下载 6,410 次，日均约 214 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @adobe/ccweb-add-on-devcert 还在维护吗？

最新版本 0\.2\.2 发布于 2025/06/27（1\.4 年前）；至今共发布 5 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/10/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。