phpenv 与 Umami 无集成关系，不能用 phpenv 安装或运行 Umami；Umami 是 Node.js 应用，依赖 Node.js 18.17+、npm/yarn 及数据库 CLI，而 phpenv 仅管理 PHP 版本，不提供 Node.js 环境。
直接说结论：phpenv 和 Umami 没有直接集成关系，不能用 phpenv 安装或运行 Umami。Umami 是 Node.js 应用，而 phpenv 只管理 PHP 版本 —— 两者运行时环境完全不同，混用会导致 command not found 或 Cannot find module 'node' 类错误。
为什么 phpenv 无法安装或启动 Umami
Umami 的运行依赖明确且固定：Node.js 18.17+（官方最新要求）、npm 或 yarn、数据库客户端（psql 或 mysql CLI）。phpenv 完全不提供 Node.js 环境，它只在 PATH 中注入 PHP 二进制和 shim，对 node、npm 命令无任何影响。
常见误操作包括：
- 在 phpenv 激活的 shell 中执行
npm install，结果报错“bash: npm: command not found”（说明 Node.js 根本没装） - 以为
phpenv local 18.17能切换 Node 版本（实际会报错：no version ‘18.17’ in phpenv） - 把
.php-version文件误命名为.node-version并期待 phpenv 识别（它完全忽略该文件）
Umami 正确的 PHP 相关使用场景
Umami 本身不用 PHP，但你可能在以下环节接触 PHP 工具链：
立即学习“PHP免费学习笔记（深入）”；
-
数据库初始化：若用 MySQL 后端，需手动执行
mysql -u root -p umami —— 这里调用的是系统 <code>mysqlCLI，和 PHP 无关；但如果你用 phpMyAdmin，那只是图形化入口，底层仍是 MySQL 协议 -
反向代理配置：Nginx/Apache 配合 Umami 时，可能复用现有 PHP 站点的 vhost 配置，需注意
location /不要被 PHP 的try_files $uri $uri/ /index.php?$args规则劫持 -
混合部署调试：同一台服务器既跑 PHP 博客又跑 Umami（Node.js），此时需确认端口不冲突（如 PHP-FPM 占
9000，Umami 默认3000）且防火墙放行正确端口
真正需要的 Node.js 环境管理方案
替代 phpenv、专为 Umami 服务的工具是 nvm（Node Version Manager）。它和 phpenv 设计理念一致，但面向 Node.js：
- 安装：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash - 安装指定 Node 版本：
nvm install 18.17.0 - 设为默认：
nvm alias default 18.17.0 - 验证：
node -v输出v18.17.0，npm -v输出对应版本
注意：不要同时用 nvm 和系统包管理器（如 apt/yum）安装 Node.js，否则 which node 可能指向错误路径，导致 yarn build 失败。
部署时最容易被忽略的权限与路径问题
即使 Node.js 和数据库都就位，以下两点仍高频导致启动失败：
-
DATABASE_URL中的主机名不能写localhost（Docker 容器内解析为容器自身，而非宿主数据库）—— 必须用host.docker.internal（macOS/Windows）或宿主真实 IP（Linux） -
.env文件必须位于umami项目根目录，且不能有 BOM 或 Windows 换行符（^M），否则npm run build会静默忽略DATABASE_URL，最终连不上库 - 首次
yarn build成功后，检查prisma/migrations/目录是否生成了时间戳命名的迁移文件夹 —— 缺失说明 schema 初始化未触发，后续yarn start必报 migration error
这些细节不写进文档，但卡住的人最多。
