// @formatter:off 是 PhpStorm 内置格式器唯一认可的跳过指令，需启用开关、严格单行注释格式（无前置空格、独占一行）、配对 // @formatter:on，且仅对 PHP 文件生效，对外部工具无效。
不能靠“锁定文件”来阻止格式化，必须用 // @formatter:off 和 // @formatter:on 明确标记代码段——文件级锁定不存在，只有局部跳过。
为什么右键“Pin Tab”或“Mark as Plain Text”对格式化无效
固定标签页（Pin Tab）只影响 UI 行为，不干预编辑器后端的格式化引擎；把文件类型强制设为 Plain Text 虽能绕过 PHP 格式器，但代价是失去语法高亮、补全、重构等所有语言支持。这不是保护，是自废武功。
-
// @formatter:off是 PhpStorm 内置格式器唯一认可的“跳过指令”，它在解析阶段就被识别，不依赖文件类型 - 只要文件被识别为 PHP（右下角显示
PHP），且Enable formatter markers in comments已启用，这对注释就生效 - Pin Tab 的作用域仅限于标签管理，和 Code Style、Actions on Save、格式化触发逻辑完全无关
// @formatter:off 失效的三个高频原因
不是注释“没用”，而是格式器根本没看到它——它只认严格格式的单行注释，且不解析上下文逻辑。
- 开头有空格或制表符：
// @formatter:off（前面多一个空格）→ 无视 - 混用注释风格：
/* @formatter:off */或# @formatter:off→ 不识别 - 写在条件分支里：
if (DEBUG) { // @formatter:off }→ 格式器按文本顺序扫描，不执行 if 判断，但这一行因缩进而被忽略 - 文件右下角显示
Plain Text或HTML→ 注释存在，但 PHP 格式器压根不启动，自然不处理
如何让 // @formatter:off 真正起作用
启用开关 + 正确写法 + 显式边界，三者缺一不可。尤其注意闭合标记漏写会导致后续全部代码失效。
立即学习“PHP免费学习笔记（深入）”；
- 进
Settings → Editor → Code Style → PHP → Enable formatter markers in comments，确保勾选（默认开，但项目级设置可能关） -
// @formatter:off必须独占一行、无前置字符、紧贴//后写，后面可跟空格，但不能换行或嵌套 - 闭合必须用
// @formatter:on，不能是// @formatter:enable（除非你开了正则匹配模式） - 标记之间不要跨函数/类定义——不是语法错误，但会让后续维护者误判作用范围
别指望它解决外部工具的格式化问题
// @formatter:off 只对 PhpStorm 内置格式器有效，对 php-cs-fixer、phpcbf 或 prettier 完全透明。
- 运行
php-cs-fixer fix时，那几行照样被重排——它根本不读这行注释 - 想让外部工具跳过某段，唯一办法是抽成独立函数并加文档说明，或改用
php-cs-fixer支持的// phpstan-ignore-line类似机制（需插件支持） - 如果同时用 PhpStorm 和 php-cs-fixer，建议只让前者管缩进/空格，后者管 PSR-12 全量规则，避免冲突
真正难的不是写对注释，而是判断「这段代码是否真的需要人工控制排版」——多数时候，与其加 @formatter:off，不如重构为可读性更强、格式器友好的结构。
