在nvim-lint中实现容器化PHP代码检查的实践方案

背景介绍

在PHP项目开发中，开发者经常面临需要同时支持多个PHP版本的情况，特别是在项目升级过渡期。传统做法是在本地安装多个PHP版本，但这种方式管理复杂且容易产生冲突。容器化技术（如Docker）为这个问题提供了优雅的解决方案，允许开发者在隔离环境中运行不同版本的PHP工具。

问题分析

当尝试在nvim-lint插件中使用容器化的PHP静态分析工具（如PHPStan）时，会遇到路径映射问题。容器内部的文件路径与宿主机不同，导致lint结果中的文件路径无法与Neovim缓冲区正确匹配，进而无法显示诊断信息。

解决方案

基础方案：Docker包装脚本

最直接的解决方案是创建一个包装脚本，通过Docker执行PHPStan：

#!/bin/bash
docker compose exec php74 php -dxdebug.mode=off vendor/bin/phpstan "$@"

然而，这种方法存在路径映射问题，因为容器内返回的是容器路径（如/var/www/html/lib/env.php）而非宿主机路径。

进阶方案：路径转换包装器

更完善的解决方案需要处理路径转换：

#!/bin/bash

last_param="${!#}"
absolute_filepath=$last_param

relative_filepath=$(realpath "$absolute_filepath" --relative-to "$(pwd)")

args=("$@")
unset 'args[-1]'
docker compose exec php74 php -dxdebug.mode=off vendor/bin/phpstan "${args[@]}" "$relative_filepath" | env X=$(pwd)/$relative_filepath jq -r '.files |= (with_entries(.key |= env.X))'

这个脚本实现了：

1. 提取要检查的文件路径
2. 转换为容器内的相对路径
3. 执行容器化PHPStan
4. 使用jq工具将结果中的容器路径转换回宿主机路径

nvim-lint配置

在Neovim配置中使用这个包装器：

{
  "mfussenegger/nvim-lint",
  opts = function(_, opts)
    local more_opts = {
      linters_by_ft = {
        php = { "phpstan" },
      },
      linters = {
        phpstan = {
          cmd = function()
            local executable = vim.fn.fnamemodify("phpstan.sh", ":p")
            return vim.loop.fs_stat(executable) and executable or error("executable not found: " .. executable)
          end,
        },
      },
    }

替代方案建议

虽然容器化解决方案可行，但项目维护者建议优先考虑本地运行lint工具。容器化方案确实增加了复杂性，特别是在路径映射和性能方面。对于简单的PHP版本管理，可以考虑：

1. 使用phpbrew等工具管理多PHP版本
2. 在CI环境中使用容器化检查
3. 对于必须使用容器的情况，确保开发环境与生产环境容器配置一致

总结

在nvim-lint中实现容器化PHP代码检查需要解决路径映射问题。通过创建智能包装脚本可以桥接容器内外环境，但会增加配置复杂性。开发者应根据项目实际需求权衡容器化方案的利弊，在开发便利性和环境一致性之间找到平衡点。