FrankenPHP依赖Caddy自动管理HTTPS，本地调试需用mkcert生成可信证书并配置Caddyfile启用tls指令，确保$_SERVER['HTTPS']='on'且PHP能正常发起HTTPS请求。
FrankenPHP 本身不直接管理 HTTPS 证书，它依赖集成的 Caddy 服务器自动处理 TLS。开启本地 HTTPS 调试的关键是让 Caddy 正确识别开发域名、信任本地证书（或跳过验证），并确保 PHP 应用能正确感知加密连接。
以下是针对本地开发调试的实操步骤，无需公网域名或 Let’s Encrypt：
✅ 确保 Caddy 已启用且 FrankenPHP 使用 Caddy 模式
FrankenPHP 默认以 caddy 模式运行（非内置 PHP-FPM 或 CLI 模式）。确认你启动的是带 Caddy 的版本：
- 启动命令应类似：
frankenphp serve或通过Caddyfile运行 - 若用
php -S或 Nginx 反代，则不属于 FrankenPHP 原生 HTTPS 场景
✅ 配置 Caddyfile 支持本地 HTTPS（推荐 localhost + mkcert）
Caddy 默认对 localhost 自动启用 HTTPS（使用自签名证书），但现代浏览器会拦截。更稳妥的方式是配合 mkcert 生成可信证书：
立即学习“PHP免费学习笔记（深入）”；
-
安装并信任根证书（仅需一次）
# Windows（管理员 PowerShell） choco install mkcert mkcert -install
-
生成本地证书（例如用于
localhost）mkcert localhost 127.0.0.1 ::1
生成
localhost.pem和localhost-key.pem，放在项目目录下（如./ssl/） -
编写 Caddyfile（同级目录）
{ # 启用实验性 HTTP/3（可选） servers { protocol { experimental_http3 } } } localhost { tls ./ssl/localhost.pem ./ssl/localhost-key.pem php_server encode zstd br }⚠️ 注意：路径必须为相对当前 Caddyfile 的路径，且文件需可读；不要用
https://localhost开头，Caddy 会自动监听:443并启用 TLS。 -
启动服务
frankenphp serve
访问
https://localhost—— 浏览器将显示安全锁，无警告（因 mkcert 根证书已系统信任）。
✅ PHP 中正确识别 HTTPS 请求
FrankenPHP + Caddy 会自动设置 $_SERVER['HTTPS'] = 'on' 和 $_SERVER['HTTP_X_FORWARDED_PROTO'] = 'https'，无需额外配置。验证方式：
<?php
var_dump([
'HTTPS' => $_SERVER['HTTPS'] ?? 'missing',
'X-Forwarded-Proto' => $_SERVER['HTTP_X_FORWARDED_PROTO'] ?? 'missing',
'REQUEST_SCHEME' => $_SERVER['REQUEST_SCHEME'] ?? 'missing',
]);输出应含 'HTTPS' => 'on'。
若为反向代理场景（如 Nginx 前置），需在 Caddyfile 中显式透传：
header_up X-Forwarded-Proto {http.request.proto}✅ 调试 HTTPS 接口（如调用 file_get_contents 或 cURL）
PHP 发起 HTTPS 请求时，需确保 OpenSSL 扩展启用，且 CA 证书路径正确：
- 检查
phpinfo()中 OpenSSL Support → enabled - 若报
cURL error 60，在php.ini中配置：curl.cainfo = "C:/path/to/cacert.pem" ; 下载自 https://curl.se/ca/cacert.pem openssl.cafile = "C:/path/to/cacert.pem"
重启 FrankenPHP（或对应 PHP 进程）。
? 小技巧：本地调试第三方 HTTPS 接口时，可用
httpbin.org测试连通性：file_get_contents('https://httpbin.org/get')应返回 JSON，无 SSL 错误。
❌ 常见失败点与绕过方案
-
Caddy 启动报
listen tcp :443: bind: permission denied
→ Windows 上需以管理员运行；macOS/Linux 需sudo或改用非特权端口（如localhost:8443），并在 Caddyfile 中写：localhost:8443 { tls ./ssl/localhost.pem ./ssl/localhost-key.pem php_server } 访问提示“您的连接不是私密连接”
→ 未执行mkcert -install，或证书未放入系统「受信任的根证书颁发机构」；重装根证书即可。PHP 里
$_SERVER['HTTPS']为空
→ Caddyfile 中没启用php_server指令，或 FrankenPHP 版本过旧（建议 ≥ v1.0.0-beta.5）。
不复杂但容易忽略。
