frankenphp 不能直接用 php think run 启动 thinkphp6，必须以静态文件服务器模式运行，documentroot 必须指向 public/ 目录，并手动配置 caddyfile 重写规则将请求转发至 index.php?s={uri}，同时需显式加载 .env 文件、确保 runtime/ 可写、使用 ^6.1 版本约束安装。
FrankenPHP 不能直接用 php think run 启动 ThinkPHP6，必须以静态文件服务器模式运行，且入口路径、重写规则、环境变量加载方式全部要重配。
FrankenPHP 的 DocumentRoot 必须指向 public/ 目录
FrankenPHP 不是传统 PHP-FPM + Web Server 组合，它自身就是 Web 服务器（基于 Caddy），所以没有「虚拟主机配置」概念，只有 DocumentRoot 和路由重写。若把项目根目录（含 think、app/、vendor/）设为 DocumentRoot，所有请求都会被拒或返回 403 —— 因为 public/ 外的目录默认禁止访问。
正确做法：
- 启动 FrankenPHP 时，用
--document-root明确指定路径：frankenphp serve --document-root ./public - 确保
./public/index.php存在且可执行（权限 644 即可，无需 +x） - 检查
public/下是否有.htaccess或Caddyfile冲突：FrankenPHP 不读.htaccess，也不自动加载项目根目录的Caddyfile，所有重写逻辑必须显式声明
URL 重写规则必须手动写进 Caddyfile
ThinkPHP6 的路由依赖将所有非静态资源请求转发到 index.php?s=xxx。FrankenPHP 默认不启用任何重写，不配就会 404（比如访问 /test 直接报错，而不是进控制器）。
在项目根目录新建 Caddyfile，内容如下：
localhost {
root * ./public
php_backend
encode zstd gzip
<pre class="brush:php;toolbar:false;">@notStatic {
not {
file {
try_files {path} {path}/ /index.php?s={uri}
}
}
}
rewrite @notStatic /index.php?s={uri}}
关键点：
-
root * ./public必须和--document-root一致，否则静态资源（CSS/JS）404 -
php_backend是 FrankenPHP 提供的内置 PHP 处理器，不可替换成php_fastcgi - 不要用 Apache 风格的
rewrite ^(.*)$ /index.php?s=$1，FrankenPHP 的rewrite不支持正则捕获变量，必须用{uri}模板变量 - 如果项目绑定了域名（如
tp6.test），把localhost替换为对应域名，并确保系统hosts已解析
.env 文件不会被自动加载，需显式调用
FrankenPHP 启动时不会像 Apache/Nginx + PHP-FPM 那样自动读取项目根目录的 .env。TP6 的 EnvLoader 在 public/index.php 中默认只在 CLI 模式下触发，Web 模式下依赖 SAPI 类型判断 —— 而 FrankenPHP 的 SAPI 是 frankenphp，不是 apache2handler 或 fpm-fcgi，导致 .env 读取失败，APP_DEBUG、数据库配置全失效。
解决方法：修改 public/index.php，在 require __DIR__.'/../vendor/autoload.php'; 后插入：
if (is_file(__DIR__.'/../.env')) {
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__.'/..');
$dotenv->load();
}
前提是你已通过 composer require vlucas/phpdotenv 安装了该组件（TP6 默认不带，但 thinkphp/framework v6.1+ 已内置兼容逻辑，建议仍显式引入以防版本差异）。
其他影响：
-
runtime/目录必须可写（FrankenPHP 进程用户需有写权限），否则日志、缓存、模板编译全部失败 -
APP_DEBUG=true生效后，错误页会显示，但 Trace 面板可能不加载 JS —— 因为public/static/路径未被重写规则覆盖，需确认静态资源 URL 正确（如/static/trace.js能 200）
Composer 安装必须锁定 ^6.1，且不能跳过 vendor/autoload.php
FrankenPHP 不执行 composer install，它只跑 PHP 代码。所以你必须在启动前确保 vendor/ 已完整安装，且 autoload.php 可被正确引入。
常见坑：
- 用
composer create-project topthink/think tp6-demo会拉到 TP8 开发版（因 latest 标签已指向 dev-main），必须加版本约束：composer create-project "topthink/think:^6.1" tp6-demo（引号防 Windows CMD 解析^） - 如果误装了 TP8，不要
composer update topthink/framework降级 —— 目录结构、命名空间、核心类名已不兼容，只能删掉vendor/和composer.lock，重装^6.1 -
public/index.php中的require路径必须是../vendor/autoload.php，不能改成vendor/autoload.php（那是旧版 TP5 写法，TP6 强制从public/入口，相对路径必须跨一层）
最后提醒：FrankenPHP 的 phpinfo() 页面里，$_SERVER['SERVER_SOFTWARE'] 显示的是 frankenphp，不是 Apache 或 Nginx —— 所有依赖 $_SERVER 做环境判断的中间件或扩展（比如某些多应用路由钩子），得确认是否适配这个 SAPI 类型。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
