改版的风险不在写新代码，而在改坏旧路径。这份文档把改版拆成“换组件 → 调样式 → 跑回归”三步，每一步都给出可判断的完成标准与回退方式。

一、适用范围

• 适用：站点组件的替换与重构，例如导航、卡片、按钮、列表；主题变量与样式的统一调整；改版上线前的回归检查与灰度发布。
• 不适用：站点框架配置与构建参数的修改，需按框架文档单独执行；后端接口协议变更；视觉稿设计与交互评审，在开发前完成。

二、准备工作

项目	要求	检查方法
代码分支	从主干拉出改版分支，不直接在主干修改	git status、git branch --show-current
依赖	已安装项目依赖，构建命令可执行	安装后执行一次本地构建
组件清单	列出要替换的组件、使用位置与影响页面	grep -rn "组件名" src/ 统计引用处
样式规范	颜色、间距、字号使用统一变量	检查是否存在硬编码色值
回归清单	覆盖首页、列表、详情、搜索、404 五类页面	写成可勾选表格

• 一次改版只处理一类改动，组件替换与样式调整分开提交。
• 改动前打标签或记录提交号，回滚时按提交号回退。

三、操作步骤

本节拆成三个子步骤，建议按顺序执行；每一步完成后先确认结果，再进入下一步。

3.1 组件替换

先替换使用面最窄的组件，保留旧组件适配层，验证通过后再扩大范围。替换时保持 props 名称与事件签名不变，调用方就不用跟着改，出问题的面会小很多。详见 3.1 组件替换。

3.2 样式调整

把硬编码的色值与间距收敛到变量，按页面逐一验证不同状态下的显示效果。变量按用途命名而不是按颜色命名，换配色时只改变量定义，不必回改组件。详见 3.2 样式调整。

3.3 回归检查

按回归清单逐页检查渲染、交互与性能，确认改版没有引入新的报错与布局问题。清单要覆盖改版未直接改动的页面，公共组件的问题往往先在无关页面暴露。详见 3.3 回归检查。

三步的顺序不能颠倒：组件与样式都稳定后再跑回归，否则每改一次都要重跑全部清单。回归通过后先合并到改版分支观察一轮，再合入主干并保留上一版构建产物。

四、验证方法

1. 执行 grep -rn "旧组件名" src/ | wc -l，预期结果为 0，说明旧组件已无引用；残留一处就可能继续加载旧样式，造成样式覆盖顺序不确定。
2. 执行 git diff --stat，预期改动集中在组件与样式目录，没有误改配置与依赖锁文件，锁文件变动通常意味着依赖被无意升级。
3. 在浏览器控制台确认无报错，用构建日志确认没有资源缺失或组件未注册的警告；警告数量与改版前对比，新增的警告要逐条确认。
4. 执行回归清单中的性能项：改版前后各跑一次 Lighthouse，LCP 与 TBT 未明显恶化；变差时要能指出具体是哪个资源或脚本导致的。

五、常见问题

现象	可能原因	处理方式
替换后页面空白	组件注册或引入路径错误	检查引入路径与注册名，查看控制台报错
样式未生效	作用域样式或选择器优先级冲突	检查 scoped 与选择器层级，避免使用 !important 压制
移动端布局错位	固定宽度或未处理换行	改用弹性布局，设置最小宽度与换行规则
交互点击无响应	事件名或参数传递变更	对照旧组件的事件签名逐个核对
构建时间明显变长	引入了体积大的依赖	按需引入，检查产物体积变化

六、回滚与注意事项

• 回滚：按改版前的提交号或标签回退，回退后重新构建并执行一次回归清单中的关键页面，确认旧版的组件与样式都已恢复。
• 注意：组件替换与样式调整分开提交，出问题时能只回退其中一类，而不是把整次改版一起撤掉。
• 注意：不要在主分支直接调试，改版分支验证通过后再合并，合并后保留旧版本构建产物一段时间，线上异常时可直接换回。

上一页3.3 发布步骤

下一页3.1 组件替换