portless 自定义证书实战如何用 mkcert 快速替换内置本地 CA让本地 HTTPS 零警告【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portlessportless 是一款用「稳定的命名本地 URL」替代端口号的本地开发代理工具——http://localhost:3000变成https://myapp.localhost默认自带本地 CA 与 HTTPS/HTTP2。本文带你用 mkcert 免费签发证书通过--cert/--key替换 portless 内置本地 CA完整走一遍自定义证书流程。为什么不用内置 CA要换成 mkcertportless 首次运行会自动生成本地 CA有效期 10 年、签发服务器证书并加入系统信任库相关逻辑见 certs.ts。对大多数场景这已经够用但以下情况你会想换成 mkcert统一证书管理团队已有 mkcert 签发的*.localhost、*.test证书想与 portless 共用同一套 CA信任更可控不想让 portless 自动生成 CA而是自己掌握签发与信任mkcert -install只需执行一次更简单的清理自定义证书文件不受portless clean删除影响源码明确保留了--cert/--key路径见 cli.ts策略合规企业环境要求所有本地证书来自团队统一的本地 CA。注意一个关键区别内置 CA 模式下portless 会按 SNI为每个子域名动态签发精确证书如api.myapp.localhost换成自定义证书后portless直接使用你提供的证书不再动态签发——所以证书必须自己覆盖所有要用到的域名通配符证书是正解。第一步安装 mkcert 并信任其 CAmacOS 用 HomebrewLinux 可用发行版包管理器安装 mkcert命令行工具无需联网访问任何页面。# macOS brew install mkcert # 将 mkcert 的本地 CA 加入系统信任库只需一次 mkcert -install执行mkcert -install后系统会提示你输入密码把 CA 装入钥匙串/系统信任库。这一步等价于 portless 首次运行时弹出的 CA 信任提示之后浏览器访问 mkcert 签发的域名不再报警告。第二步签发覆盖 .localhost 的自定义证书portless 默认使用.localhost后缀如https://myapp.localhost因此证书至少要覆盖localhost和*.localhostmkcert localhost *.localhost输出两个文件localhost1.pem—— 服务器证书对应--certlocalhost1-key.pem—— 私钥对应--key如果你还启用了自定义 TLDportless proxy start --tld test把域名一起签进去mkcert localhost *.localhost *.test 小建议把两个文件重命名为cert.pem/key.pem放到固定目录方便后面写进启动服务配置。第三步用 --cert/--key 启动 portless 代理portless proxy start --cert ./cert.pem --key ./key.pem官方 HTTPS 文档中正是以 mkcert 作为自定义证书示例见 https/page.mdx。参数解析与 PEM 校验逻辑在 cli.ts有三个行为值得记住行为说明必须成对出现--cert和--key缺一不可否则报错退出传入即启用 HTTPS使用自定义证书隐含开启 HTTPS监听 443严格 PEM 校验证书须包含-----BEGIN CERTIFICATE-----私钥须为-----BEGIN ...PRIVATE KEY-----格式不符直接报错随后像平时一样启动应用portless myapp next dev # - https://myapp.localhost 走你的 mkcert 证书此时 portless跳过内置 CA 生成与信任流程终端也不会再出现 Adding CA to system trust store 的输出。第四步验证证书是否生效浏览器打开https://myapp.localhost点地址栏锁形图标查看证书——颁发者应是mkcert 的 CA而不是 portless Local CA命令行体检portless doctordoctor会检查代理存活、路由、DNS 与 CA 信任状态。检测到自定义证书时它会直接输出 Proxy is configured with a custom TLS certificate并提示内置 CA 已不再需要见 cli.ts查看当前路由portless list持久化让开机服务也使用自定义证书如果你把代理装成了操作系统启动服务portless service install该命令同样接受--cert和--key配置会写入 launchd / systemd / 任务计划程序重启后依然生效portless service install --cert ~/certs/cert.pem --key ~/certs/key.pem portless service status # 查看已安装的端口、HTTPS 模式等相关命令说明见 commands/page.mdx。常见问题与回退浏览器仍报证书错误九成是 mkcert 的 CA 没装进信任库重跑mkcert -install或证书没覆盖该域名检查 SAN 里是否有对应的通配符。换 TLD 后部分域名失效因为自定义证书模式下不再有动态签发把新 TLD 加入mkcert重新签发再portless proxy stop portless proxy start --cert ... --key ...重启代理。想切回内置 CA停掉代理后不带--cert/--key重新启动即可portless proxy stop portless proxy start # 重新走内置 CA 流程可用 portless trust 补信任清理注意portless clean会移除内置 CA 与状态文件但永远不删除你通过--cert/--key提供的文件可放心清理。小结portless 内置本地 CA 开箱即用当你需要统一的证书策略或团队共享 CA 时用 mkcert 签发一份覆盖localhost、*.localhost及自定义 TLD的证书再通过portless proxy start --cert ./cert.pem --key ./key.pem替换即可——两条命令换证书本地 HTTPS 依旧零警告。项目完整功能与更多命令见 README.md。【免费下载链接】portlessReplace port numbers with stable, named local URLs. For humans and agents.项目地址: https://gitcode.com/GitHub_Trending/por/portless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考