发生了什么

商家端是一套给商户用的手机端管理页面。商户登录后可以查看自己店铺的信息,也可以配置给顾客的免费时长,也就是顾客在什么条件下能免费使用一段时间。这类页面不是每个功能各做一个网页,而是把脚本打包成一份文件:手机先下载并执行这份脚本,脚本再把标题、表格、按钮画到页面上,然后向后端取数据填进去。

正常打开的顺序是:商户在手机上进入商家端,浏览器下载这份打包脚本,脚本执行成功,页面框架出现;商户点开免费时长,同一份脚本切换到对应页面,取回配置并显示。只要脚本跑起来,后面的取数据和渲染都是常规步骤。

这一次,在一台特定机型的手机上打开同一个入口,页面是空白的:看不到任何内容,也没有可读的报错提示。排查后确认,这台手机内置的浏览器内核停留在 2019 年的版本;而项目打包时,只把项目自己写的源码转成了老内核看得懂的写法,用到的部分第三方库按发布时的原样被拼进了产物。也就是说,业务代码本身没有写错,问题在于发给这台手机的这份脚本里,有一段它读不懂的代码。

本质

浏览器执行脚本分两步:先把整份脚本读成它能理解的语法,再一句一句执行。只要有一处语法不认识,整份脚本会停在解析阶段,后面的逻辑一句都不执行,它不会跳过看不懂的那几行、把其余部分跑完。这一点决定了故障的样子:页面内容要靠这份脚本画出来,脚本没跑,商户看到的就是空白,而不是某个按钮点不动或者某块数据显示不出来。

出问题的先后顺序是:

  1. 打包时,构建工具按配置把项目源码降级成老内核能接受的语法,转换范围只覆盖项目自己的源码目录。
  2. 第三方库以发布到公共仓库时的形态参与打包,其中的新语法没有被转换,原样进入最终产物。
  3. 老内核浏览器拿到产物,在解析阶段遇到不认识的语法,整份脚本报错退出。
  4. 负责把内容挂到页面上的那段代码没有执行,商户看到空白页面,也没有可读的提示。
  5. 开发和测试阶段使用的浏览器内核较新时,同一份产物能正常跑,问题不会在功能验收里暴露,直到这台旧内核手机真实访问才出现。

这里有两处容易被忽略。一是“只编译自己的代码”是构建工具的默认行为,依赖默认不参与转换,升级某个依赖就可能悄悄把新语法带进产物,而按功能点验收时看不出产物语法有什么问题。二是这类故障按访问设备的浏览器内核分布,同一份代码在新内核上完全正常,逐项点功能的回归测试几乎发现不了差别。

修复方向是:在构建配置里把这些第三方库也纳入转换范围,让产物里不再出现目标内核读不懂的语法;并把“产物语法与目标浏览器版本对齐”固定为构建约定,上线前用旧内核设备真实打开一次页面。记录里给出的处理是编译时把那部分不支持老机型的第三方库一起加进去,是否已经上线并验证,记录没有说明。

错误代码

// 第三方库发布到仓库里的代码(示意),直接使用了较新的语法
// node_modules/lib-name/dist/format.js
export const label = (cfg) => cfg?.name ?? "未命名";
// 为什么错:?. 和 ?? 是 2019 年之后才被支持的新语法,
// 老内核浏览器在解析这一句时就报错,整份脚本都不会执行

// 构建配置:只转换项目自己的源码
module.exports = {
  entry: "./src/main.js",
  module: {
    rules: [{
      test: /\.js$/,
      exclude: /node_modules/,   // 为什么错:第三方库被原样拼进产物,
                                 // 没有任何一步把它降级成老内核能读懂的写法
      use: "babel-loader"
    }]
  }
};

修复代码示例

// 构建配置:把确认含新语法的第三方依赖也纳入转换范围
const path = require("path");

module.exports = {
  entry: "./src/main.js",
  module: {
    rules: [{
      test: /\.js$/,
      include: [
        path.resolve(__dirname, "src"),
        path.resolve(__dirname, "node_modules/lib-name")  // 依赖一起降级编译
      ],
      use: {
        loader: "babel-loader",
        options: {
          // 目标对齐线上仍会访问的最低内核版本,产物语法不再超出它
          presets: [["@babel/preset-env", { targets: { chrome: "78" } }]]
        }
      }
    }]
  }
};

两段代码是脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。

下次遇到这些场景要警惕

  • 升级或新增第三方依赖后:不要只在新版内核上点一遍功能,用一台内核停留在旧版本的设备打开受影响的页面,先看控制台有没有语法错误,再确认页面内容是否正常渲染。
  • 调整构建配置或编译范围时:用同一份产物分别在最新内核和旧内核上打开,确认两边都能画出内容;只有新内核通过,不算通过。
  • 遇到“某机型页面一片空白、没有任何提示”的反馈:先确认脚本是不是在解析阶段就整份失败,再去查产物里有没有目标内核不认识的语法,而不是先怀疑接口返回、权限或数据为空。
  • 收集这类反馈时:把机型、系统浏览器内核版本和页面表现一起记录,按内核版本判断影响范围,避免同款机型不同系统版本被漏掉。