整站源码交接前的避坑清单

拿到一份整站源码，真正的风险往往不在代码能不能跑起来，而在交接之后三五天里逐渐暴露的结构问题。下面这份清单按“先看骨架、再验数据、后查权限”的顺序组织，适合在验收、二次开发接手、迁移部署前逐条过一遍。

一、文件结构与依赖声明
先确认目录分层是否与文档一致：入口文件、配置目录、静态资源、上传目录、日志目录是否各自独立。常见坑是把配置写死在入口文件里，或把上传目录混在代码目录中，导致后续升级覆盖用户文件。检查依赖声明文件是否完整，锁文件是否存在；如果只有依赖清单没有锁文件，说明版本不可复现，部署到新环境极易出现版本漂移。还要留意是否存在硬编码的绝对路径、写死的本地地址、只在特定系统下可用的路径分隔符。判断标准很简单：把源码解压到一个全新路径，不改任何配置，看能否定位到所有被引用的文件。

二、数据与配置的可迁移性
数据库结构应有可重复执行的初始化脚本，而不是只给一份导出的数据快照。快照能跑，但无法说明字段约束、索引和默认值的设计意图。检查配置项是否集中管理，敏感项是否与代码分离；如果密钥、连接信息散落在多个文件，迁移时必然遗漏。上传目录、缓存目录、日志目录要能被识别为“可丢弃”或“必须保留”两类，交接文档里应明确写出哪些目录不能覆盖。另一个高频坑是时区与字符集：源码里对时间的处理若混用本地时间与统一时间，迁移到不同区域后会出现排序错乱。验收时可以构造一条跨日数据，观察列表排序与详情显示是否一致。

三、权限、计划任务与外部依赖
检查运行账号的最小权限是否被正确描述：哪些目录需要写、哪些只需读、哪些必须禁止执行。很多交接事故源于给整个目录开放写权限，短期能跑，长期留下隐患。计划任务与常驻进程要有清单，写清触发频率、失败重试方式、日志位置；缺少这份清单，接手者往往在问题出现后才发现有后台任务在跑。外部依赖方面，确认调用的接口、存储、消息通道是否有替代方案或降级路径，避免单点依赖。最后做一次“断网演练”：在无外部依赖的环境下启动，观察报错是否清晰、是否给出可操作的提示。清晰的失败比静默的成功更有价值。

四、验收动作与留痕
建议按“清空环境重建”的方式验收：新建目录、重新安装依赖、重新初始化数据、重新配置权限，全程记录每一步命令与结果。任何需要人工记忆的步骤都应转化为脚本或文档条目。交接清单末尾留一栏“未验证项”，把暂时无法确认的内容写清楚，比假装全部通过更负责。整站源码的价值不在于一次能跑，而在于下一次接手的人能否在不询问原作者的情况下独立完成部署与排错。