PSR-4和PSR-12是PHP项目协作与CI/CD的硬性门槛，关乎自动加载、静态分析及第三方库集成；需严格遵循大小写、路径映射、命名空间结尾斜杠、函数格式、PHPDoc规范及strict_types声明。
PHP项目一旦超过三人协作或进入CI/CD流程，不按PSR-4和PSR-12落地，Class not found、Unexpected token、php-cs-fixer --dry-run报错就会变成日常。这不是风格偏好问题，是能否被Composer加载、能否被PHPStan分析、能否被Monolog或Guzzle无缝集成的硬性门槛。
PSR-4自动加载失败的典型现象与修复路径
本地开发一切正常，上线Linux直接报Class 'AppHttpControllersusercontroller' not found——这是最常被忽略的大小写陷阱。Windows/macOS文件系统不区分大小写，但Linux严格区分，而Composer完全依赖路径字面量匹配命名空间。
- 检查
composer.json中"psr-4"配置是否以反斜杠结尾："App\": "src/"✅，"App": "src"❌（缺尾部斜杠+缺转义） - 确认类文件路径与命名空间完全对齐：类
AppHttpControllersUserController必须存于src/Http/Controllers/UserController.php，不能是src/controllers/usercontroller.php - 禁止在类名中用下划线分隔单词：
AppModelsUser_Info会映射到src/Models/User_Info.php，但PSR-4不解析_为目录分隔符（那是已废弃的PSR-0行为） - 执行
composer dump-autoload --optimize后，删掉所有require/include语句——PSR-4生效的前提是零手动加载
PSR-12格式化为什么不能靠“感觉”来写
PSR-2早在2019年就被官方标记为废弃，现在所有主流工具（php-cs-fixer、phpcs）默认都不再支持它。PSR-12不是“更宽松的PSR-2”，而是专为PHP 7.4+设计的语法适配规范，比如它明确定义了enum、match、构造器属性提升的格式，也允许namespace与use之间空行——这些细节手动维护极易出错。
-
function关键字后**不能有空格**：function handle(): void {✅，function handle (): void {❌ - 控制结构如
if后必须有空格，但函数调用括号前**不能有空格**：if ($user->isActive())✅，if( $user->isActive() )❌ - 返回类型声明格式必须为
): int（冒号前后各一空格），不是):int或): int - 方法体左花括号
{必须与function声明同行，且其后必须换行+4空格缩进
PHPDoc注释不是可选项，是接口契约的一部分
PSR-12要求所有公共方法必须带完整PHPDoc块，不是为了好看，而是为了让PHPStan、Psalm这类静态分析工具能准确推导类型流。缺少@param或写成mixed，会导致整个函数体类型检查失效。
立即学习“PHP免费学习笔记（深入）”；
- PHPDoc块必须紧贴函数声明正上方，中间**不能插空行**；首行描述必须是单句、大写开头、句号结尾
-
@param顺序必须与参数声明顺序一致，类型要精确：string|int✅，mixed❌；可空类型写?string，不是string|null -
@return不可省略，void也必须显式写出；禁止在return语句前加空行 - 内联注释
//必须独占一行，不能挂在代码行末尾，且缩进层级需与对应代码对齐
最容易被跳过的其实是declare(strict_types=1)——它必须出现在每个PHP文件的首行（除<?php 标签外），否则哪怕写了int $id，PHP也不会做运行时类型校验。这个细节不强制，但一旦漏掉，后续所有类型声明都形同虚设。
