前言入口文件是 ThinkPHP 项目里最不起眼、也最容易被写坏的一个文件。它通常只有五六行看起来毫无技术含量但它承担着三个结构性职责定义应用边界、加载自动加载器、把请求交给应用内核。这三个职责里任何一个出问题表现都是「整个站点打不开」而错误信息往往指向别处。关于入口文件有三个常见的误解。第一个是以为入口文件里可以随便写代码。它确实是一个普通的 PHP 文件你可以在里面 echo、可以连数据库、可以写业务逻辑——但在里面输出任何内容都会破坏后续的响应头在里面写业务逻辑则会让「每次请求都执行一遍」这件事变得难以追踪。第二个是以为一个项目只能有一个入口文件。ThinkPHP 天然支持多个入口管理后台一个入口、接口一个入口、定时任务一个入口各自绑定到不同的模块或应用。这是「单一入口」这个说法的常见误读——说的是每个请求都经由某个入口文件而不是说全站只能有一个入口文件。第三个是以为入口文件的位置可以随便放。它的位置决定了 Web 服务器的文档根目录该指向哪里而文档根目录决定了哪些文件能被浏览器直接访问。入口文件放在项目根目录等于把application目录和配置文件一起暴露出去。本文以入口文件的三个职责为主线讲清它在不同版本中的写法、多入口的定义方式以及哪些代码不该写在这里。一、入口文件的三个职责一个入口文件无论长什么样做的都是这三件事。职责具体动作出问题的表现定义应用边界声明应用目录、环境标识等常量找不到控制器、缓存写到错误位置加载自动加载器引入 Composer 的 autoload类不存在的致命错误交给应用内核构造应用、运行、发送响应、收尾白屏、500、响应头异常第一件事是「定义应用边界」。ThinkPHP 5.0 的入口文件里能看到这一职责最直白的表达?php // 适用于 ThinkPHP 5.0// [ 应用入口文件 ]// 定义应用目录define(APP_PATH, __DIR__ . /../application/);// 加载框架引导文件require __DIR__ . /../thinkphp/start.php;APP_PATH告诉框架「应用代码在哪里」。注意它结尾的那个斜杠——很多框架级的常量都要求以目录分隔符结尾漏掉它会出现路径拼接错误例如applicationconfig.php这种拼在一起的名字。这类错误的表现是「配置文件读不到、全部走了默认值」非常隐蔽。第二件事是「加载自动加载器」。ThinkPHP 6 的入口文件把这一点暴露得很清楚?php // 适用于 ThinkPHP 6.x// [ 应用入口文件 ]namespace think;require __DIR__ . /../vendor/autoload.php;// 执行HTTP应用并响应$http (new App())-http;$response $http-run();$response-send();$http-end($response);require的路径一律用__DIR__拼绝对路径。用相对路径是入口文件里最经典的一个坑入口文件被 Web 服务器执行时当前工作目录取决于服务器的配置可能是 PHP 的安装目录也可能是站点目录而不是入口文件所在目录。本地php -S能跑放到 IIS 或 Apache 下就报「文件不存在」原因就在这里。注意这里的run()、send()、end()三个步骤是分开的不是一句run()就完事。分开写的好处是在send()之前你有机会对响应做统一处理比如统一加安全响应头在end()里框架会做请求收尾写日志、清理。如果把它们揉成一行这些介入点就都没有了。第三件事是「交给应用内核」。这一步的顺序不能颠倒必须先有自动加载器才能new App()必须先run()得到响应对象才能send()。把send()写在run()前面是新手常犯的顺序错误。二、多入口绑定模块与应用ThinkPHP 支持在一个项目里定义多个入口文件每个入口绑定到不同的模块或应用从而实现「前台一套、后台一套」的物理隔离。ThinkPHP 5.0 的写法是在入口文件里定义一个常量?php // 适用于 ThinkPHP 5.0保存为 public/admin.php// [ 后台入口文件 ]// 定义应用目录define(APP_PATH, __DIR__ . /../application/);// 把本入口绑定到 admin 模块define(BIND_MODULE, admin);// 加载框架引导文件require __DIR__ . /../thinkphp/start.php;绑定之后访问/admin.php就等于进入admin模块URL 里不再需要写模块名。ThinkPHP 6 里「模块」这个概念在默认配置下已经不存在了默认是单应用模式多入口绑定的是应用。写法变成在入口文件里给 Http 对象指定应用名?php // 适用于 ThinkPHP 6.x保存为 public/admin.php// [ 后台入口文件 ]namespace think;require __DIR__ . /../vendor/autoload.php;$http (new App())-http;// 指定本次请求由 admin 应用处理$response $http-name(admin)-run();$response-send();$http-end($response);需要说明的是ThinkPHP 6 的多应用能力需要通过扩展启用具体的方法名与配置方式请以对应版本官方文档为准无论哪种写法核心思路是一样的入口文件负责声明「这次请求归谁处理」。多入口方案的价值可以用一张表看清方案优点代价单一入口 路由区分部署简单只有一份 rewrite 规则前后台代码在同一应用内权限边界靠代码纪律维持多入口 绑定不同应用物理隔离清晰可分别做访问控制与限流每个入口都要配 rewrite静态资源路径要理清多入口不等于更安全。很多人做多入口的真实动机是「后台入口改成admin_x8f2.php别人猜不到」。这是一种「隐蔽即安全」的思路它只能降低被自动扫描器扫到的概率不能替代认证与授权。真正的安全边界是登录校验、权限判断、以及后台接口的独立性不是文件名的隐蔽程度。三、入口文件里该写什么、不该写什么入口文件是一个「每次请求都会执行」的位置。这句话是判断代码该不该放在这里的唯一标准。可以放在这里定义常量应用目录、环境标识、版本号加载自动加载器绑定应用或模块加载额外的环境初始化文件例如提前解析.env注册全局的错误与异常处理器统一给响应加安全头在send()之前不该放在这里任何形式的输出。echo、print、var_dump甚至文件末尾多出来的一个空行都会让响应头发出之前已经有内容导致header()调用失败、下载文件损坏、JSON 响应前面多出空白字符。业务逻辑。放在这里的逻辑既不归属任何模块也拿不到请求对象还要在每次请求包括静态资源以外的所有请求里执行一遍。慢操作。连接数据库、调用外部接口、扫描大目录都会直接抬高所有请求的响应时间底线。硬编码的密钥。入口文件经常被误提交到版本库也常常在排错时被复制给别人看。一个符合上述原则的入口文件示例在 ThinkPHP 6 的基础上加了统一安全响应头?php // 适用于 ThinkPHP 6.x// [ 应用入口文件 ]namespace think;require __DIR__ . /../vendor/autoload.php;$http (new App())-http;$response $http-run();// 在 send() 之前统一加固响应头$response-header([X-Content-Type-Options nosniff,X-Frame-Options SAMEORIGIN,Referrer-Policy strict-origin-when-cross-origin,]);$response-send();$http-end($response);这些响应头解决的是很具体的问题X-Content-Type-Options: nosniff阻止浏览器根据内容猜测类型防止上传的文本文件被当成脚本执行X-Frame-Options阻止页面被其他站点用框架嵌套点击劫持Referrer-Policy控制跳转时带出去的来源信息。它们不能替代输出转义和参数化查询但属于成本极低、收益明确的一层加固。还有一件事值得在入口文件里做环境标识的显式声明。生产环境和开发环境的配置来源不同如果在入口处就把环境说清楚可以避免「线上误开了调试模式」这种事故。ThinkPHP 通过.env文件或环境变量区分环境部署脚本里必须保证生产环境的.env不进版本库、且只有服务进程可读。四、入口文件与部署的配合关系入口文件放在哪里直接决定了服务器的文档根该设成哪里。三者的关系必须一致组件该指向说明入口文件项目目录下的public/index.php全站唯一物理入口Web 文档根项目目录下的public绝不能是项目根目录重写规则把不存在的路径转给index.phpNginx / Apache / IIS 各写各的如果文档根设成了项目根目录会发生什么浏览器可以直接访问你的域名/config/database.php。在很多服务器配置下PHP 文件会被执行而不是下载那倒还好但只要服务器上 PHP 处理程序配置有一点偏差.env、composer.json、runtime下的日志和缓存文件就可能被完整下载走。一个更隐蔽的风险是编辑器生成的临时文件。很多编辑器在保存时会留下index.php~、index.php.swp这类备份文件这些文件不会被 PHP 处理程序执行而是被当作纯文本下载。文档根指向public时即使产生了这类文件它也只暴露入口文件本身的内容指向项目根时暴露的是全部源码。# Nginx文档根指向 public并把不存在的路径转给入口文件root /path/to/project/public;index index.php;location / {if (!-e $request_filename) {rewrite ^(.*)$ /index.php?s$1 last;}}# Apache在 public 目录下放 .htaccessIfModule mod_rewrite.cRewriteEngine OnRewriteCond %{REQUEST_FILENAME} !-fRewriteCond %{REQUEST_FILENAME} !-dRewriteRule ^(.*)$ index.php?s$1 [L]/IfModule从本地开发切到生产部署时还有一件事必须确认php -S内置服务器不做重写所以本地开发时地址里通常带着index.php而生产环境不带。这个差异会让「本地能跑的 URL 线上 404」。解决办法是在本地也配一个路由脚本让两者的行为对齐。常见坑点❌ 入口文件放在项目根目录❌ 文档根 项目根浏览器可访问 /config/database.php✅ 入口文件放 public文档根指向 public✅ 文档根 项目根/public❌require用相对路径// ❌ 当前工作目录随服务器配置变化线上找不到文件require ./vendor/autoload.php;✅ 用__DIR__拼绝对路径require __DIR__ . /../vendor/autoload.php;❌ 入口文件里输出调试信息忘了删// ❌ 响应头已经发出后续 header() 全部失败echo debug;✅ 入口文件里不做任何输出// 用日志而不是 echo 做调试❌APP_PATH忘了结尾的斜杠// ❌ 路径拼接出错配置文件读不到而静默走默认值define(APP_PATH, __DIR__ . /../application);✅ 保留结尾的目录分隔符define(APP_PATH, __DIR__ . /../application/);❌ 把send()写在run()前面// ❌ 响应对象还不存在直接致命错误$http-send();$response $http-run();✅ 顺序是 run、处理、send、end$response $http-run();$response-send();$http-end($response);❌ 在入口文件里连数据库、调接口// ❌ 这些操作会在每个请求里都执行一遍$pdo new PDO($dsn, $user, $pass);✅ 把这类操作放到服务层按需执行// 入口文件只负责引导不做实际工作❌ 以为多个入口文件能提升安全性❌ 把后台入口改名成 admin_x8f2.php 就以为安全了✅ 安全靠认证与授权不靠文件名✅ 每个后台接口都做登录态校验与权限判断❌ 本地用php -S直接跑生产带重写两边 URL 形态不一致❌ 本地 /index.php/index/hello线上 /index/hello✅ 本地也配路由脚本让行为对齐// 本地用 php -S localhost:8000 router.php 启动总结事项结论核心职责定义应用边界、加载自动加载器、交给应用内核位置项目目录下的public文档根必须指向public路径写法一律用__DIR__拼绝对路径执行顺序先run()拿到响应再处理再send()最后end()多入口通过绑定模块5.x或指定应用6.x实现本质是声明请求归属能写的代码常量、引导、绑定、全局处理器、统一响应头不能写的代码任何输出、业务逻辑、慢操作、硬编码密钥部署配套文档根指向public并对齐重写规则入口文件之所以重要是因为它站在「应用」和「服务器」的交界处两边的约定都靠它来兑现服务器约定「所有动态请求都交给你」应用约定「你负责把我启动起来」。也正因为它每次请求都要执行、且出错时影响全站写在这里的每一行代码都要经得起「它会不会在每次请求里跑一遍」这一问。把入口文件保持得足够短、足够干净是让整个项目可调试、可部署、可交接的基础。文中写法以 ThinkPHP 5.0 与 6.x 的公开接口为准5.1 的差异与 6.x 多应用扩展的具体用法请以对应版本的官方文档为准。