FrankenPHP 怎么开启 HTTPS 本地证书调试项目-php教程-PHP中文网

frankenphp依赖caddy自动管理https，本地调试需用mkcert生成可信证书并配置caddyfile启用tls指令，确保$_server['https']='on'且php能正常发起https请求。

frankenphp 怎么开启 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 生成可信证书：

安装并信任根证书（仅需一次）

# 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。

btpanel phpsite 宝塔面板PHP网站
宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载
启动服务
```
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）。