最近一个合作了很久的老朋友，让我帮忙配合她国外的团队一起管理一个网站。
一开始这个站是我自己搭的 WordPress 环境，后来他们做 SEO 的时候，国外团队觉得效率不高，就要求换成 Kirby CMS。可能后面人手也紧张，又让我一起跟进这个项目，于是我就硬着头皮接手了——这是我第一次正经用 Kirby。
一通邮件来回之后，终于拿到了 GitHub 权限，然后照着他们的文档部署测试环境。
他们给的推荐环境是：
- Homestead
- VirtualBox + Vagrant
- Homestead scripts repo
- Docker & Docker Compose
- nvm（或类似工具）
- 不需要数据库
说实话，这一整套我都不太习惯。我平时更偏向直接在 VPS 上部署，于是还是在美国的 VPS 上，用宝塔面板手动搭了环境。
前面一堆操作其实还算顺利，虽然中间有点小波折，但前台最终是成功跑起来了，页面正常输出。当时还有点小欣喜，立马回了封邮件说一切顺利。
结果一进后台，直接打脸。
Kirby CMS 的后台（Panel）是独立模块，装好之后，后台直接报错：
Field "intro_text": The field type "markdown" does not exist
Field "sections": The field type "builder" does not exist
完全懵了，这是我第一次接触 Kirby。
只能疯狂问 AI。
一会儿说是文件权限问题，一会儿说 PHP 版本问题，一会儿又说插件兼容、PHP 扩展……
我换了好几个 AI（Gemini、GPT、DeepSeek），来回折腾，还把一堆源文件丢给它们分析，结果全都没用。
从早上搞到下午下班，毫无进展。
晚上吃完饭，我换了个思路，在自己的 MacBook 上重新部署一遍。
本来是 XAMPP 环境，但 PHP 版本不好切，就干脆用 Homebrew 升级了 PHP，MySQL 继续用 XAMPP 的，然后用 `php -S` 启了个服务。
结果：后台报错一模一样。
而且图片全挂了（这个在宝塔上反而是正常的）。
查了一圈，才在 Kirby 官方文档里看到一句：
PHP built-in server is not recommended for Kirby Panel development
没办法，只能再装一套 Valet，用 Nginx 环境跑。
Valet 启动之后，伪静态问题解决了，更关键的是——后台错误直接消失了，一切正常。
当时真的是一脸懵。
我开始对比 Mac 上这两种环境的区别，重新问 AI，这次终于定位到了核心原因：
JS / CSS / 图片资源没有被 index.php接管。
这一下我就明白了。
宝塔 Nginx 默认有一条规则：
location ~ .*\.(js|css)?$ {
expires 12h;
error_log /dev/null;
access_log /dev/null;
}
这条规则会导致：
- js / css直接由 Nginx 返回
- 不会进入 Kirby 的 `index.php
- 而 Kirby 的 Panel 插件，必须能识别插件目录下的 JS
- 这些 JS 需要通过 Kirby 的路由机制（伪静态）来处理
也就是为什么前面 AI 一直让我检查插件目录下有没有 JS 文件——文件是有的，但根本没机会被 Kirby 接管。
这条规则是宝塔默认生成的，非常隐蔽。
再加上对 Kirby CMS 完全不熟，结果在这个问题上硬生生耗了十几个小时。
在这里简单记录一下，希望以后有人踩到同样的坑，能更快定位问题。
额外踩坑记录
数据库迁移报错
使用他们团队提供的数据库迁移命令时，报错：
In ExceptionConverter.php line 91:
An exception occurred while executing a query:
SQLSTATE[42000]: Syntax error or access violation:
1071 Specified key was too long; max key length is 3072 bytes
解决方法：
修改 migrations.php`文件：'version_column_length' => 1024 改为：'version_column_length' => 767 即可。
Cloudflare SSL（灵活模式）下 HTTPS 识别问题
在 Cloudflare SSL灵活模式下，Kirby CMS 无法正确识别 HTTPS：$_SERVER['HTTPS'] === null
解决方法：
在对应域名的配置文件中强制指定 URL，例如：site/config/config.example.com.php,加入：'url' => 'https://example.com'
注意事项：
如果宝塔绑定了多个域名
- 要么删除多余域名
- 要么把主域名排在最前
- 否则 Kirby 可能仍然识别错误
整体就是这么个过程。
一次很典型的「环境 + CMS 特性 + 默认配置」叠加造成的深坑。
另外，宝塔部署需要配置伪静态，php版本选8.3, 安装mbstring、 Memached等扩展，以及nodejs
