phpenv仅管理PHP版本，不安装Kimai；需先用phpenv切换至8.1+版本并手动编译启用pdo_mysql等扩展，再通过Composer、数据库配置及Web服务器独立部署Kimai。
phpenv 本身不直接安装 Kimai，它只负责管理 PHP 版本。Kimai 是一个基于 PHP 的 Web 应用，需要你先用 phpenv 准备好兼容的 PHP 环境（如 8.1+），再按标准方式部署 Kimai。很多人卡在「以为装了 phpenv 就能一键跑 Kimai」，其实中间缺了关键一环：PHP 运行时能力补全。
确认 Kimai 所需的 PHP 版本和扩展
Kimai 2 要求 PHP ≥ 8.1，且必须启用以下扩展：pdo_mysql、curl、json、mbstring、xml、zip、opcache。仅靠 phpenv install 8.1.28 不会自动编译这些——它默认只带最简扩展。
-
phpenv安装的 PHP 默认不含 MySQL 驱动（pdo_mysql），因为依赖系统级的libmysqlclient或mariadb-client开发包 - Windows 上用
phpenv极其受限（官方未适配），实际资料中提到的「Windows +phpenv」多为混淆；你看到的 Windows 教程里用的是 ZIP 包直装 PHP，不是phpenv - Linux/macOS 下，安装前必须先装系统依赖：
sudo apt install libmysqlclient-dev libxml2-dev libssl-dev libsqlite3-dev zlib1g-dev
- 安装时建议显式传参启用关键扩展：
PHP_BUILD_CONFIGURE_OPTS="--with-pdo-mysql --enable-opcache" phpenv install 8.1.28
用 phpenv 切换到 Kimai 兼容版本后，仍需手动拉取和配置 Kimai
phpenv 不处理 Composer、数据库、Web 服务器或环境变量。部署 Kimai 的核心步骤仍得自己执行：
- 切换到目标 PHP 版本：
phpenv global 8.1.28
然后验证：php -v和php -m | grep pdo_mysql必须有输出 - 拉取 Kimai 源码（不是用
phpenv）：git clone <a href="https://www.php.cn/link/ccce275184c5d8f1fea8923c49d9f396">https://www.php.cn/link/ccce275184c5d8f1fea8923c49d9f396</a> /var/www/kimai - 进入目录后，用系统级 Composer（非
phpenv自带的）安装依赖：cd /var/www/kimai && composer install --no-dev --optimize-autoloader - 创建
.env.local并填入DATABASE_URL="mysql://user:pass@127.0.0.1:3306/kimai" - 执行 Doctrine 命令建库建表：
php bin/console doctrine:database:createphp bin/console doctrine:schema:create
常见失败点：PHP 版本对得上，但 php -m 缺扩展或报 Class 'PDO' not found
这不是 Kimai 的错，是 phpenv 编译时漏了扩展或共享库路径不对：
立即学习“PHP免费学习笔记（深入）”；
- 检查
php --ini输出的配置文件路径，打开php.ini，确认以下行未被注释：extension=php_pdo.dll（Windows）或extension=pdo.so（Linux/macOS）extension=php_pdo_mysql.dll或extension=pdo_mysql.so - Linux/macOS 下，若提示
Cannot load module 'pdo_mysql'，大概率是extension_dir指向错误目录，或.so文件根本不存在于该目录 - Windows 用户请放弃用
phpenv：它不支持 Windows，你实际用的是 PHP 官方 ZIP 包 + 手动配置 PATH，和phpenv无关
别指望 phpenv 启动 Kimai —— 它没这个功能
phpenv 是版本切换工具，不是应用服务器。Kimai 启动靠的是：
- 内置 PHP 服务器（仅开发用）：
php -S 0.0.0.0:8000 -t public/ - 或 Nginx/Apache 反代（生产用），此时你要配好
root、index、try_files，并确保 PHP-FPM 使用的是phpenv指定的版本（通过php-fpm -v验证）
最关键的细节常被忽略：Kimai 的 public/ 目录才是 Web 根目录，不是项目根目录；用内置服务器时必须加 -t public，否则路由 404。这个路径问题和 phpenv 无关，但新手几乎必踩。
