企业官网建设流程全解析

PHPantom 是一款用 Rust 编写的高性能 PHP 语言服务器，其内置的fix命令可以批量自动修复整个项目中的代码问题。一条命令、几秒钟，就能清理掉成百上千个未使用的use语句——无需逐文件手动处理。本文介绍PHPantom fix 命令在实际开发中最常用的 10 种场景，帮助你快速上手。

📦 工作原理：与编辑器共享同一引擎

fix命令并不是一个独立的修复脚本，它运行的是与编辑器 LSP完全相同的分析引擎。你在编辑器里看到的每一个诊断，fix都能识别并修复。

整个流程分四步（源码见 src/fix.rs）：

💡 规则通过诊断码字符串标识：原生规则直接使用标识符（如unused_import），PHPStan 规则使用phpstan.前缀（如phpstan.return.unusedType）。

基本用法与参数速查

# 运行所有推荐的原生修复器（默认） phpantom_lsp fix # 只运行指定规则（可重复） phpantom_lsp fix --rule unused_import --rule deprecated # 预览模式：显示会修改什么，但不写入文件 phpantom_lsp fix --dry-run # 只修复指定目录 / 单个文件 phpantom_lsp fix src/ phpantom_lsp fix src/Foo.php

完整参数说明参见 docs/cli.md。

退出码

10 种典型修复场景

以下场景全部来自 PHPantom 的集成测试（tests/integration/fix_cli.rs），覆盖了unused_import规则的各种边界情况。

场景 1：一键清理整个项目

最直接的用法——不加--rule，直接运行：

phpantom_lsp fix

它会扫描项目中所有 PHP 文件和 Blade 模板，找出所有未使用的use语句并批量删除。一个有数百个冗余导入的 Laravel 项目，几秒钟就能清理干净。

修复完成后的典型输出：

------ ------------------------------------------- Line src/Service/UserService.php ------ ------------------------------------------- 5 Unused import 'App\Models\LegacyUser' 🔧 unused_import 6 Unused import 'App\Support\OldHelper' 🔧 unused_import ------ ------------------------------------------- [FIXED] Applied 2 fixes across 1 file

场景 2：只修复指定目录或文件

大型项目中，你可能只想清理src/目录，或者修复某个刚改过的文件。路径参数直接跟在命令后面即可：

phpantom_lsp fix src/ phpantom_lsp fix src/Service/UserService.php

场景 3：dry-run 预览——先看看会改什么

在真正修改文件之前，用--dry-run预览所有改动。输出与正常模式相同，但文件不会被修改，退出码为2。非常适合在 CI 中作为"未使用导入检查"的门禁：

# CI 门禁：发现未使用导入就失败，但不修改文件 phpantom_lsp fix --dry-run --rule unused_import --project-root . --no-colour

场景 4：智能保留正在使用的导入

fix命令不会盲目删除use语句。以下情况中引用的导入会被自动保留：

• 参数 / 返回值类型提示：function bar(User $user)中的User
• docblock 注释：@return User中的User
• 静态方法调用：Helper::doSomething()中的Helper
• new表达式：new User()

只有文件中完全没有任何引用的use语句才会被移除。

场景 5：组导入（Group Import）的成员级精准清理

PHP 8 支持组导入语法use App\Models\{User, Post, Comment};。fix能处理到成员级别：

// 修复前 use App\Models\{User, Post, Comment}; // 假设只有 User 被使用，修复后 use App\Models\{User};

如果组导入中所有成员都未使用，则整条use语句被删除。

场景 6：多行组导入

当组导入跨越多行时（常见于 IDE 自动格式化后的长导入列表），fix同样能正确处理，且不会在组内留下多余空行：

// 修复前 use App\Models\{ User, Post, }; // 修复后（Post 未使用，被移除） use App\Models\{ User, };

带别名的成员（如Post as BlogPost）也能正确识别和处理。

场景 7：括号命名空间（Braced Namespace）

PHP 允许在同一个文件中用大括号定义多个命名空间。fix命令能正确处理这种结构：

namespace App { use App\Models\User; // 被使用 → 保留 use App\Models\Post; // 未使用 → 移除 class Foo { ... } }

场景 8：trait 的 use 语句不会被误删

use在 PHP 中有两种含义：命名空间导入和 trait 使用。fix只清理命名空间级别的use，类内部的 trait 使用完全不受影响：

use App\Traits\HasName; // 命名空间导入，类内 trait 使用它 → 保留 class Foo { use HasName; // trait 使用，不会被修改 }

场景 9：Blade 模板中的 @use 指令

PHPantom 对 Blade 模板有专门的处理逻辑。模板中的@use指令和@php块内的use语句都能被正确修复：

{{-- 修复前 --}} @use('App\Models\User') {{-- 被使用，保留 --}} @use('App\Models\Post') {{-- 未使用，移除 --}} @use('App\Models\{Tag, Team}') {{-- Tag 未使用，被移除 --}} <div>{{ User::query()->count() }} {{ Team::first() }}</div> {{-- 修复后 --}} @use('App\Models\User') @use('App\Models\{Team}') <div>{{ User::query()->count() }} {{ Team::first() }}</div>

模板的 HTML 部分完全不受影响。

场景 10：CI 集成——pre-commit hook 或 CI gate

fix命令天然适合集成到 CI 流水线中。以下是几种常见模式（完整示例见 docs/cli.md）：

Pre-commit hook——每次提交前自动清理导入：

phpantom_lsp fix --rule unused_import --project-root .

CI 门禁——发现未使用导入就让构建失败：

phpantom_lsp fix --dry-run --rule unused_import --project-root . --no-colour

组合使用——先修复，再检查剩余问题：

phpantom_lsp fix --project-root . phpantom_lsp analyze --project-root .

💡 退出码2在--dry-run模式下表示"发现了可修复的问题"，CI 脚本可利用这一点判断是否需要让构建失败。

空行处理与幂等性保证

fix命令在删除导入时会智能处理空行：

• 删除整行导入后，相邻空行自动合并
• 从导入块中间删除一行，不会在剩余行之间留下空行
• 删除组导入的个别成员后，组内的空行会被清理

这保证了修复后的代码始终整洁，无需再跑一遍格式化。

fix命令还是幂等的——运行两次和运行一次的结果完全相同。如果所有问题已经修复完毕，再次运行会输出：

[OK] No fixable issues found

并直接以退出码0结束，不写入任何文件。

与 analyze / format 命令的配合

fix只是 PHPantom CLI 工具链中的一环。完整的代码质量管理流程通常是：

# 1. 自动修复可修复的问题 phpantom_lsp fix # 2. 格式化代码（使用项目已有的 Pint / php-cs-fixer / 内置格式化器） phpantom_lsp format # 3. 检查剩余的结构性问题（未解析的类、成员、函数等） phpantom_lsp analyze --severity warning

三者运行的是同一个引擎，结果完全一致。fix处理能自动修复的，format统一风格，analyze报告需要人工处理的部分。

可用规则一览

目前fix命令支持的原生规则：

PHPStan 规则（phpstan.前缀）和更多原生规则（如deprecated、unused_variable）正在规划中，详见 docs/todo/fix-cli.md。

快速上手

如果你还没安装 PHPantom，只需两步：

phpantom_lsp fix --dry-run # 先预览 phpantom_lsp fix # 确认无误后真正执行

整个项目的冗余导入就清理完了。

PHPantom 的fix命令源码位于 src/fix.rs，代码操作实现见 src/code_actions/，集成测试见 tests/integration/fix_cli.rs，完整 CLI 参考文档见 docs/cli.md。