# generate-certs 中文文档

规范地址：https://npmcn.com/package/generate-certs/

版本：4\.0\.0
npm 元数据更新时间：2026-11-03T17:11:36.861Z
中文译文更新时间：2026-11-03T18:10:40.779Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/generate-certs
原文对照：https://npmcn.com/package/generate-certs/?lang=original
项目主页：https://github.com/WolfieLeader/npm/tree/main/packages/generate-certs#readme
源码仓库：https://github.com/WolfieLeader/npm

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

- 包体积（解压后）：94.2 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：1 个
- 首次发布：2024-11-20T12:34:28.831Z
- 最新版本发布：2026-11-03T17:11:36.472Z
- 已发布版本数：14（近 12 个月 3 个）

## 中文简介

️本地开发轻松生成HTTPS证书

## 安装

```sh
npm install generate-certs
```

也可以使用：`pnpm add generate-certs`、`yarn add generate-certs`、`bun add generate-certs`

## README

![banner](https://github.com/WolfieLeader/npm/blob/main/assets/generate-certs-banner.svg)

# 发电证书

用于本地开发的自签名HTTPS证书。  
自动生成、验证和重用。

[![License](https://img.shields.io/github/license/WolfieLeader/npm?color=DC343B)](https://opensource.org/licenses/MIT) [![npm version](https://img.shields.io/npm/v/generate-certs?color=0078D4)](https://www.npmjs.com/package/generate-certs) [![npm downloads](https://img.shields.io/npm/dt/generate-certs.svg?color=03C03C)](https://www.npmjs.com/package/generate-certs) [![stars](https://img.shields.io/github/stars/WolfieLeader/npm)](https://github.com/WolfieLeader/npm)

> **不是为了生产。** 这些是仅用于本地开发的自签名证书。对于生产，请使用受信任的CA，如 [让我们加密](https://letsencrypt.org/)。

## 亮点✨

-   **自动生成证书** -不需要OpenSSL
-   **智能重用** -验证过期、权限和密钥/证书配对
-   **为localhost预配置** - - - - - - `127.0.0.1`， `::1`, `localhost` 无
-   **框架就绪** - Express, NestJS, Hono, fasttify
-   **安全文件权限** 执行(Unix: `600` （私钥）

## 安装📦

需要Node.js >= 22.12。建议作为dev依赖项。

```bash
npm install -D generate-certs
# or
pnpm add -D generate-certs
```

## 快速启动🚀

```typescript
import path from "node:path";
import https from "node:https";
import express from "express";
import { generateCerts } from "generate-certs";

const certs = generateCerts({ certsPath: path.resolve(import.meta.dirname, "../certs") });

const app = express();
https.createServer(certs, app).listen(3443);
```

## API参考📖

### `generateCerts(options): { key: string; cert: string }`

从指定的目录生成或检索自签名证书。如果有效证书已经存在，则会重新使用它们。返回 `{ key: string; cert: string }` 作为pem格式的字符串，准备好 `https.createServer()`。

```typescript
import path from "node:path";
import { generateCerts } from "generate-certs";

// Auto-generates key.pem and cert.pem (or reuses valid existing ones)
const certs = generateCerts({ certsPath: path.resolve(import.meta.dirname, "../certs") });
console.log(certs.key); // "-----BEGIN RSA PRIVATE KEY-----\n..."
console.log(certs.cert); // "-----BEGIN CERTIFICATE-----\n..."

// Print what happened (reuse, permission fix, backup, generation)
const logged = generateCerts({
  certsPath: path.resolve(import.meta.dirname, "../certs"),
  logger: console.log,
});
```

**选项:** `certsPath` （必选，证书目录的绝对路径）， `logger` (可选 `(message: string) => void`；省略时为静音)。

**抛出** 如果路径无效、不可访问或证书生成失败。

## 证书详情📜

| 财产 | 价值 |
| --- | --- |
| 关键算法 | RSA 2048位 |
| 签名 | sha - 256 |
| 有效性 | 1年后的一代 |
| 通用名 | `localhost` |
| 主题名称 | `localhost`， `127.0.0.1`， `::1` |
| 基本约束 | `CA:FALSE` (关键) |
| 密钥使用 | 数字签名、密钥加密（关键） |
| 扩展密钥用法 | TLS Web服务器身份验证 |
| 私钥权限 | `600` (Unix) |

## 智能重用♻️

现有的 `key.pem` 和 `cert.pem` 当所有这些条件都满足时，文件才会被重用：

1.  **文件存在** -两个文件都存在
2.  **到期** —证书未过期或5分钟内即将过期
3.  **在此之前** -证书已经有效
4.  **无** 他们包括 `localhost`， `127.0.0.1`, `::1`
5.  **关键尺寸** -RSA密钥至少为2048位
6.  **键/ cert配对** -私钥与证书匹配
7.  **Self-signature** -自行颁发的证书根据自己的密钥进行验证

来自您自己的CA的证书（例如，mkcert）通过这些检查并保存下来。未选中“公共名称”。

如果 `key.pem` 可由组或其他人读取，则其模式更改为 `600` (Unix)。这些文件被保存了下来。

如果任何检查失败，则将现有文件复制到 `key.pem.bak` 和 `cert.pem.bak` (模式 `600`)，则生成一个新的对。较旧的备份永远不会被覆盖; 后来的备份被命名为 `key.pem.1.bak`， `key.pem.2.bak`等等。如果备份失败，则不会重新生成任何内容。

## 框架示例🧩

### NestJS

```typescript
import path from "node:path";
import { NestFactory } from "@nestjs/core";
import { generateCerts } from "generate-certs";
import { AppModule } from "./app.module";

const certs = generateCerts({ certsPath: path.resolve(import.meta.dirname, "../certs") });

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { httpsOptions: certs });
  await app.listen(3443);
}

bootstrap();
```

### HonoJS

```typescript
import { createSecureServer } from "node:http2";
import path from "node:path";
import { serve } from "@hono/node-server";
import { generateCerts } from "generate-certs";
import { Hono } from "hono";

const certs = generateCerts({ certsPath: path.resolve(import.meta.dirname, "../certs") });

const app = new Hono();

serve({
  fetch: app.fetch,
  port: 3443,
  createServer: createSecureServer,
  serverOptions: certs,
});
```

### Fastify

```typescript
import path from "node:path";
import Fastify from "fastify";
import { generateCerts } from "generate-certs";

const certs = generateCerts({ certsPath: path.resolve(import.meta.dirname, "../certs") });

async function bootstrap() {
  const app = Fastify({ https: certs });
  await app.listen({ port: 3443, host: "0.0.0.0" });
}

bootstrap();
```

## 最佳实践✅

-   **添加 `certs/` 来 `.gitignore`** -永远不要将生成的证书提交到版本控制
-   **作为dev依赖项安装** （`-D`) -在生产环境中不需要这个包
-   **预期会出现浏览器警告** -自签名证书将显示 “不安全”; 单击 “高级” → “进入本地主机”
-   **默认情况下，日志处于关闭状态** ——通过 `logger: console.log` 看看发生了什么

> **窗口:** Windows系统跳过文件权限检查。

> **并发性：** 锁定文件 (`.generate-certs.lock`) 序列化并发调用。只有当它的所有者进程消失或超过60秒时，锁才会被接管。

## v4中的重大变化⚠️

-   **需要Node.js >= 22.12。**
-   **`activateLogs` 被替换为 `logger`。** 默认情况下，日志记录是关闭的。通过 `logger: console.log` 以恢复v3输出。
-   **Common Name不再被选中。** 具有其他cn或无的有效证书将被保留而不是替换。
-   **保存ca颁发的证书。** v3需要自签名并替换mkcert样式的证书。
-   **一个不安全的 `key.pem` 模式是固定的，没有更换。** 键保留其内容并获得模式 `600`。如果无法更改模式， `generateCerts` 抛出。
-   **在重新生成之前备份了无效文件** 作为 `*.bak`。
-   **对现有证书进行验证 `node:crypto`** （`X509Certificate`)，因此可以接受EC和Ed25519密钥对。
-   **生成的证书携带 `basicConstraints`， `keyUsage`, `extKeyUsage`。**
-   **`node-forge` 是 `^1.4.2`**,它修复了2026年10月建议 (包括PEM重做和签名伪造)。

## 类型导出🏷️

```typescript
import type { GenerateCertsOptions } from "generate-certs";
```

## 致谢🙏

建立在 [node-forge](https://www.npmjs.com/package/node-forge) 用于生成RSA密钥和创建X.509证书。

## 贡献🤝

-   打开一个 [问题](https://github.com/WolfieLeader/npm/issues) 或者特性请求
-   提交PR以改进包装
-   如果你觉得它有用，就用星号标记它

  

精心制作 [WolfieLeader](https://github.com/WolfieLeader)

该项目根据 [麻省理工学院的许可](https://opensource.org/licenses/MIT)。

## 常见问题

### generate-certs 是什么？

️本地开发轻松生成HTTPS证书

### 如何安装 generate-certs？

在项目目录运行 npm install generate-certs，或使用 pnpm add / yarn add / bun add。

### generate-certs 支持 TypeScript 吗？

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

### generate-certs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### generate-certs 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### generate-certs 可以商用吗？

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

### generate-certs 还在维护吗？

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