TP5函数文件必须在框架初始化阶段绑定加载路径，不能用if-else运行时加载，否则会破坏自动加载契约，导致组件初始化时报“Call to undefined function”，且CLI与Web行为不一致。
TP5 的函数文件不能靠 if-else 在运行时动态加载，必须通过环境变量 + 配置驱动，在框架初始化阶段完成加载路径的绑定。
为什么在控制器或公共文件里用 if (APP_ENV === 'production') require 'func_prod.php' 会出问题
这种写法看似直观，但破坏了 TP5 的自动加载契约：函数文件需在容器注册前就可用，否则模型、验证器、中间件等依赖自定义函数的组件会在初始化时找不到方法而报 Call to undefined function。更严重的是，它绕过了框架的配置加载顺序，导致 CLI 命令（如 php think optimize:schema）和 Web 请求行为不一致——CLI 可能没加载函数，Web 却加载了。
- TP5 启动流程中，
thinkphp/base.php会先执行load_functions()，再初始化容器；这个时机无法被运行时条件干预 -
APP_ENV是运行时才读取的环境变量，而函数加载必须发生在框架启动早期（甚至早于config/目录扫描） - 不同入口（
index.php、admin.php、command.php）可能各自 require，造成重复加载或漏加载
正确做法：把函数文件按环境分目录，用 extra.function_files 配置项控制
ThinkPHP 5.x 支持在 composer.json 中声明 extra.function_files，该数组中的 PHP 文件会在框架启动时自动 require_once。关键在于——这个数组可以由 Composer 脚本根据环境变量动态生成。
- 在项目根目录建两个函数目录：
functions/dev/和functions/prod/，各自放对应环境的辅助函数 - 修改
composer.json的extra段："extra": { "function_files": [ "functions/common.php" ] } - 添加 Composer 脚本（
composer.json的scripts）："post-autoload-dump": [ "@php -r "file_put_contents('functions/_env_list.php', '<?php return [\'' . ($_ENV['APP_ENV'] ?? 'local') . '\' => true];');"" ] - 在
thinkphp/base.php加载逻辑后追加一行（或通过public/index.php入口手动补）：$env_funcs = include ROOT_PATH . 'functions/_env_list.php'; if (isset($env_funcs[APP_ENV])) { $env_dir = ROOT_PATH . 'functions/' . APP_ENV; foreach (glob($env_dir . '/*.php') as $f) { require_once $f; } }
更轻量的方案：用 .env 控制单个函数文件路径
如果只是少量函数（比如仅 dev 需要调试函数），可直接在 config/app.php 中用 env() 动态拼路径，再由框架自动加载：
- 确保
config/app.php中已启用env解析（默认开启） - 在
config/app.php底部追加：'function_file' => env('FUNC_FILE', 'functions/common.php'), - 在
public/index.php开头（define('APP_PATH', ...)之后）插入：if ($func = config('app.function_file')) { $path = ROOT_PATH . $func; if (is_file($path)) { require_once $path; } } - 开发环境
.env写：FUNC_FILE=functions/dev/debug.php；生产环境留空或写FUNC_FILE=functions/prod/helper.php
真正容易被忽略的是：函数文件里的代码必须是纯声明式（只定义函数、不执行逻辑），且不能依赖尚未初始化的容器服务（如 Db::name()）。一旦出现“函数里调用了模型”，就会在框架启动早期触发致命错误——这不是环境切换的问题，而是加载时机与依赖顺序的根本错配。
