phpstorm原生支持@formatter:off/on跳过局部格式化，需在设置中启用formatter markers；仅识别行注释、独占一行、无前置空格；不适用于php cs fixer等外部工具。
怎么用 @formatter:off/on 跳过局部格式化
PhpStorm 原生支持通过行内注释控制格式化范围，无需插件或额外配置。只要在 Settings > Editor > Code Style > PHP > Formatter 中勾选 Enable formatter markers in comments，就能生效。
常见错误现象：加了 // @formatter:off 却没效果——大概率是没启用这个开关，或者用了错的注释格式（比如写成 /* @formatter:off */，它只认行注释）。
-
// @formatter:off必须独占一行，且不能有前置空格或制表符 - 关闭标记
// @formatter:on同样必须独占一行 - 两个标记之间所有代码（包括语法错误、多行字符串、DSL 片段）都不会被
Ctrl + Alt + L或保存时格式化触碰 - 标记本身不会被删除或移动，格式化后仍保留在原位
为什么 @formatter:off 不适用于 PHP CS Fixer
这是工具边界问题：PHP CS Fixer 和 PhpStorm 内置格式化器完全独立。前者是 CLI 工具，不解析注释指令；后者是 IDE 内置引擎，才识别 @formatter:off。
如果你在项目中同时使用两者，要注意：即使你在代码里写了 // @formatter:off，php-cs-fixer fix 依然会处理那几行——它根本看不到这行注释。
- 想让
php-cs-fixer跳过某文件，只能靠notPath()或exclude()配置 - 想局部跳过，唯一可行路径是把那段代码抽成独立函数，再在函数名/注释里说明“此逻辑需保持原始排版”
- 别指望
// @phpcs:disable在 PhpStorm 里起作用——它对 PhpStorm 格式化器无效，对 PHP CS Fixer 也无效
格式化标记的高级用法与坑点
默认只认 @formatter:off 和 @formatter:on，但可以开启正则匹配，实现更灵活的标记策略。
比如在 Settings > Editor > Code Style > PHP > Formatter 中勾选 Use regular expressions for formatter markers，然后填入：
Off pattern: @formatter:(off|disable|skip) On pattern: @formatter:(on|enable|resume)
这样你就能混用 // @formatter:skip 和 // @formatter:enable，方便团队协作或历史代码兼容。
- 正则模式一旦启用，原始字符串标记（如
@formatter:off）依然有效，不必替换旧代码 - 注意正则语法错误会导致整个标记功能失效，建议先测试简单表达式
- 标记只影响格式化（indent/spacing/wrapping），不影响代码检查、语法高亮或自动补全
哪些场景下必须用标记，而不是改规则
不是所有排版问题都能靠调整 Tabs and Indents 或 Wrapping and Braces 解决。当代码结构本身承载语义时，硬套规则反而破坏可读性。
典型例子：SQL 拼接、协议字段位运算、数学公式展开、DSL 链式调用。
- 比如一段带缩进的 SQL 字符串：
$sql = "SELECT a, b FROM table WHERE id IN (1, 2, 3)";—— 格式化器可能把它压成单行，反而难读 - 又比如位掩码计算：
$flag = ($a & 0xFF) | ($b —— 强制换行或空格会打乱视觉分组 - 这类代码一旦被重排，人工 review 成本远高于禁用标记的成本
真正容易被忽略的是：标记只在 PhpStorm 内部格式化流程中生效，CI 流水线里跑的 php-cs-fixer 或 phpcbf 完全不认它——如果团队规范要求“所有格式必须由 CLI 工具统一处理”，那这些标记就只是临时开发辅助，上线前得清理或同步到外部工具配置里。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
