PHP兼容CLI与Web模式的写法操作指南

本文深入解析了PHP在CLI与Web环境下的关键差异及兼容性实践，强调通过统一入口、显式环境判断（推荐使用`str_starts_with(PHP_SAPI, 'cli')`而非硬编码比对）和逻辑解耦来实现“一套代码双模运行”；涵盖输入参数适配封装、绝对路径安全构建（基于`__DIR__`）、彻底规避`session`/`cookie`/`header`等Web专属函数在CLI下的致命错误，并指出真正难点在于将环境相关副作用从核心业务逻辑中剥离——让开发者无需重复修改业务层即可灵活支持命令行调度与HTTP请求，大幅提升代码复用性与可维护性。

PHP 脚本在 CLI 和 Web（如 Apache/FPM）下运行时，$_SERVER、$_GET、$_POST 等超全局变量行为差异大，直接混用容易报错或逻辑错乱。兼容的关键不是“写两套”，而是统一入口 + 显式环境判断。

怎么判断当前是 CLI 还是 Web 模式

别依赖 php_sapi_name() 返回值字符串硬比对（比如写成 === 'cli'），它在某些嵌入式 SAPI 或 Docker 环境下可能返回 cli-server、phpdbg 等变体。稳妥做法是用 PHP_SAPI 常量配合前缀判断：

• if (str_starts_with(PHP_SAPI, 'cli')) { /* CLI 分支 */ }
• Web 场景更推荐反向判断：if (!str_starts_with(PHP_SAPI, 'cli')) { /* Web 分支 */ }，覆盖 fpm-fcgi、apache2handler、litespeed 等常见 Web SAPI
• 避免用 isset($_SERVER['HTTP_HOST']) —— CLI 下可能被伪造（比如通过 curl -H 启动），不可靠

如何统一读取参数：CLI 的 $argv 和 Web 的 $_GET/$_POST

不要在业务逻辑里反复写 if (CLI) { $input = $argv[1]; } else { $input = $_GET['id'] ?? $_POST['id']; }。应封装一个输入适配器：

function get_input(string $key, $default = null) {
    if (str_starts_with(PHP_SAPI, 'cli')) {
        // CLI：按位置或 --key=value 解析（简单场景直接用 $argv）
        $index = array_search('--' . $key, $GLOBALS['argv']);
        if ($index !== false && isset($GLOBALS['argv'][$index + 1])) {
            return $GLOBALS['argv'][$index + 1];
        }
        // 回退到按顺序取（如 php script.php value）
        $pos = 1;
        if ($key === 'arg1') $pos = 1;
        if ($key === 'arg2') $pos = 2;
        return $GLOBALS['argv'][$pos] ?? $default;
    }
    // Web：优先 POST，再 GET，最后 fallback
    return $_POST[$key] ?? $_GET[$key] ?? $default;
}

调用时统一写 get_input('user_id', 0)，业务层完全无感。

为什么 __DIR__ 和路径操作在 CLI 下容易出错

CLI 没有“当前请求路径”概念，__DIR__ 是脚本所在目录，但 chdir() 可能被调用过，getcwd() 不一定等于 __DIR__。Web 模式下，多数框架会把工作目录设为项目根，而 CLI 默认是执行命令的目录。

• 绝对路径一律基于 __DIR__ 或 dirname(__FILE__) 构建，例如：require __DIR__ . '/config/database.php';
• 避免 include 'config.php' 这类相对路径，CLI 下极大概率报 failed to open stream
• 日志路径若用 __DIR__ . '/../logs/app.log'，要确保目录存在且 CLI 用户有写权限（Web 用户通常是 www-data，CLI 是当前 shell 用户）

session、cookie、header 相关函数在 CLI 下必须绕开

CLI 模式下调用 session_start()、setcookie()、header() 会直接触发警告甚至 fatal error，因为没有 HTTP 上下文。

• 所有涉及输出控制的代码块，必须包裹环境检查：if (!str_starts_with(PHP_SAPI, 'cli')) { session_start(); }
• 不要在公共函数里隐式调用这些函数 —— 即使当前只在 Web 下用，未来加个 CLI 调度任务就崩
• 替代方案：CLI 下用 file_put_contents() 记日志、用 json_encode() 输出结构化结果；Web 下才走 header() + HTML 渲染

真正难的不是判断模式，而是把“环境相关”的副作用（IO、输出、状态管理）从核心逻辑里彻底剥离。一旦耦合进业务方法，每次新增 CLI 入口都要翻查并打补丁。

今天关于《PHP兼容CLI与Web模式的写法操作指南》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！