接手老旧PHP项目：二次开发中的源码审计与安全加固实战

接手一个运行多年的 PHP 项目，最容易踩的坑不是不会写新功能，而是误判改动范围。很多旧系统的问题并不在单个函数里，而在入口文件、配置、依赖、会话处理、数据库访问和第三方回调之间长期耦合。二次开发前如果直接改业务代码，很可能新功能还没上线，原有的登录、支付、导出或回调流程先出现异常。更稳的做法是把这次接手当成一次源码审计和安全加固：先确认项目能不能在目标 PHP 版本下稳定运行，再识别依赖风险和代码质量问题，最后按模块小步修复 BUG。

先把版本兼容性和依赖边界摸清楚

旧项目的第一轮审计，不要从业务逻辑开始，而要从运行环境和依赖边界开始。先在独立测试环境中部署项目，并用 php -v 确认当前 PHP 版本。如果线上仍运行 PHP 5.x 或较早的 PHP 7.x，不要直接在生产环境升级，而是先搭建 PHP 7.4、PHP 8.1、PHP 8.2 等目标版本环境，观察项目在不同版本下的报错差异。

这里要重点看的不是语法是否能运行，而是三类变化：类型约束变严后原本靠隐式转换通过的代码是否开始报错；废弃函数、废弃扩展和废弃配置项是否仍被核心流程使用；错误处理机制变化后，原来被静默吞掉的问题是否会变成致命错误。对于 WordPress 主题、插件或自定义 PHP 模块来说，这类问题经常出现在模板加载、钩子回调、表单提交处理和旧版数据库访问层里。

依赖检查同样要在动代码之前完成。如果项目使用 Composer，需要同时查看 composer.json 和 composer.lock。前者说明项目声明的依赖约束，后者说明当前实际锁定的版本。审计时不要只关注“有没有安装依赖”，而要判断依赖是否长期未更新、是否存在版本冲突、是否锁定了已经停止维护的包，以及是否引入了有已知安全问题的组件。对于老旧项目，供应链风险常常比业务代码本身更危险，因为一个过期依赖可能同时带来兼容性问题和安全漏洞。

一个可操作的判断顺序是：先保证项目能在目标 PHP 版本中启动，再确认核心路由、登录、数据库连接、文件上传和第三方回调可以走通，然后再处理依赖升级。升级时优先选择只包含安全修复和小幅兼容性修正的版本，不要一次性把主要依赖全部升到最新大版本。旧项目改造最怕的不是升级慢，而是一次升级引入过多未知变化，导致问题无法归因。

用 PHPStan 和 Composer 建立可追踪的质量基线

版本和依赖边界清楚之后，下一步是建立代码质量基线。PHPStan 的价值不是“跑一遍然后修完所有报告”，而是帮助你把旧项目中的高风险区域暴露出来。对老旧项目来说，直接从高严格等级开始通常不可行，因为历史代码会产生大量问题，团队很快会被报告淹没。更合理的方式是从较低等级开始，先关注会影响运行稳定性的错误，再逐步提升检查强度。

使用 PHPStan 时，建议把扫描重点放在控制器、认证逻辑、支付或订单回调、文件上传、数据库查询封装和所有直接处理用户输入的位置。这些地方一旦存在类型误判、空值未处理、参数缺失或返回值结构变化，就可能直接造成线上故障。对于旧项目，先不要急着重构所有命名不规范或结构不优雅的代码，而是优先处理会导致安全风险和运行异常的问题。

Composer 在这里承担的是依赖安全审计角色。除了查看依赖版本约束，还要关注依赖包是否有已知安全公告、是否仍接收维护、是否被锁定在不再修复漏洞的版本上。如果发现某个依赖已经长期无人维护，但项目又深度依赖它，不要马上替换，而是先评估它的调用点是否集中，能否通过适配层隔离。直接替换底层依赖，往往会让原本隐藏的业务差异一下子暴露出来。

为了让审计结果可追踪，最好把 PHPStan 和 Composer 检查纳入固定流程。可以放在本地开发阶段，也可以接入 CI/CD，在每次提交或合并前运行。对旧项目而言，更重要的是建立“变更前后差异可比较”的机制：这次提交新增了哪些静态分析错误，是否触碰了高风险目录，是否修改了认证、上传、数据库访问或回调验签逻辑。这样后续出现问题时，可以快速定位是业务改动导致的，还是依赖升级导致的。

安全加固优先处理可被外部触发的入口

旧项目的安全问题，通常不是均匀分布在所有文件里，而是集中在少数可被外部触发的入口。审计时应优先检查用户输入、文件上传、登录认证、权限判断、数据库查询和第三方回调。这些位置一旦被绕过，影响面远大于普通后台管理页面的代码质量问题。

对用户输入，不能只做简单 trim 或前端校验。所有进入数据库查询、HTML 输出、命令执行、文件路径拼接或第三方接口调用的数据，都应被视为不可信数据。数据库访问应改为预处理语句并绑定参数，避免拼接 SQL。输出到页面的内容要做转义和过滤，降低 XSS 风险。文件上传则需要限制类型、大小和存储位置，避免上传目录具备执行权限。

如果项目包含第三方平台回调，例如支付通知、企业微信回调、消息推送或 Webhook，必须验证请求来源。不能只相信请求体中的业务字段，而要检查签名、时间戳、随机串和回调地址是否符合预期。很多旧系统当年为了快速上线，只做了业务逻辑，没有做请求验证，这在现在是非常高风险的缺口。

配置管理也属于安全审计的一部分。数据库账号、密钥、Token、 salts、第三方 AppSecret 等配置不应硬编码在业务代码里，更不应该随代码仓库公开传播。对旧项目来说，发现配置泄露后，不只是移动文件位置那么简单，还需要评估相关密钥是否已经暴露，必要时轮换密钥并检查访问日志。

模块化修复 BUG：先隔离，再小步替换

当审计发现大量问题时，不要试图一次性重写整个项目。二次开发成功的关键，是区分底层架构缺陷和表层逻辑错误。很多看似混乱的代码，其实承载着真实业务规则，比如特殊折扣、历史订单状态、旧版会员等级、兼容老客户端的返回格式。贸然重写，很容易把这些隐性规则一起丢掉。

更稳妥的方式是模块化修复。先用 Git 创建独立分支，并保留原始代码备份。每一个 BUG 修复都应有明确边界：它修的是哪个入口、哪个服务、哪个数据表、哪个返回结构。修复前先复现问题，修复后只验证与该模块相关的行为。若某个函数被多个业务流程调用，不要直接改函数内部逻辑，而是考虑新增适配层，让旧调用方保持原有行为，新调用方走新的安全实现。

这类做法在旧项目里尤其重要。比如一个旧的查询函数同时被后台列表、前台页面和导出 CSV 使用，直接修改返回字段可能导致三个地方同时异常。更安全的做法是保留原函数作为兼容入口，在内部调用新的安全查询服务，再逐步把调用方迁移过去。迁移时每次只改一个调用点，并记录变更前后的返回差异。

如果项目已有测试，修复 BUG 时应先补充能复现问题的测试；如果没有测试，至少要通过日志、快照或手工检查清单记录关键路径。对于登录、支付、回调、权限判断这类高风险流程，不能只靠“页面看起来正常”来判断修复完成，而要检查异常分支、空值分支和非法请求分支是否也按预期处理。

把旧项目改造变成可复用流程

接手老旧 PHP 项目时，真正需要建立的不是某个技巧，而是一套可复用的改造顺序。先搭独立环境，确认 PHP 版本兼容性；再梳理入口文件、配置文件、核心类和依赖关系；接着用 PHPStan 和 Composer 建立代码质量与依赖安全基线；最后按模块修复 BUG，优先处理可被外部触发的安全风险。

这个流程的核心不是追求一步到位，而是让每一次改动都可追踪、可回滚、可归因。旧项目并不怕代码旧，怕的是改动没有边界。只要版本评估、依赖审计、静态分析、安全入口加固和模块化修复能形成闭环，二次开发就不再是凭经验冒险，而会变成一套可以反复执行的工程方法。