小程序开发里有一种最难受的失败:所有自动化检查全绿,
一进模拟器就崩。typecheck 零错误、三百多个单测全过,
模拟器控制台却甩出一行 module 'core/ai.js' is not defined。
这是我在「一语控物」项目里踩到的真实一幕,根因值得单独写一篇。
01现场:三条报错,一条都不是原因
module 'core/ai.js' is not defined, require args is './core/ai'
Component is not found in path "wx://not-found"
Page "index" has not been registered yet
第一反应是去查后两条——组件路径、页面注册。全是死胡同。
真相是:后两条是结果,不是原因。app.js
在启动时 require 了崩掉的模块,装配流程中断,页面和组件根本没来得及注册。
修好第一条,后两条自动消失。报错信息的呈现顺序和因果顺序是相反的,
这是排查的第一课。
02根因:require 不是你以为的 require
出问题的代码长这样:
import { DapCodec } from '../dap'; // ❌ 真机/模拟器找不到
import { DapCodec } from '../dap/index'; // ✅ 必须显式写 /index
关键事实:小程序的 require 是编译器插桩函数,
它只做一件事——把相对路径拼上 .js 后缀去查找,
不做 Node/npm 风格的「目录 → index.js」回退。
而坑就坑在:TypeScript(moduleResolution: "node")和 Jest
都支持省略 /index。于是出现了这条完美的裂缝:
tsc --noEmit:按 Node 规则解析,找得到 → 绿- Jest:走 Node 解析,找得到 → 绿
- 小程序运行时:只拼
.js,找不到 → 崩
三个环境里两个支持、一个不支持,而那个不支持的是唯一会暴露在用户面前的。 「npm run verify 全绿,模拟器直接崩」就是这么来的。
可以复用的判断:当你的工具链里有多个解析器, 「全绿」只覆盖了实现解析规则的那几个。 真正的运行环境可能用的是最笨的那条解析规则—— 而它没有测试覆盖,因为它在开发者工具里,不在 CI 里。
03修法:约定 + 把约定变成规范
单点修复就是把 /index 补上。但真正要做的是防止再犯——
这个项目把它写进了开发规范 §2.2,三条导入规则:
// ✅ 跨层引用:显式 /index,只从层的出口进
import { DapCodec, DapValidator } from '../dap/index';
// ❌ 穿透到层内部文件(破坏封装)
import { DapCodec } from '../dap/codec';
// ❌ 省略 index —— 小程序运行时找不到
import { DapCodec } from '../dap';
层内部文件之间可以直连(同目录单文件,不涉及目录解析); tests/ 下的 spec 不受约束(走 Node 解析,两种写法皆可)。
04同一家族的另外几个坑
排查过程中顺手排掉的同族问题,根源都是「小程序运行时 ≠ 标准 JS 运行时」:
| 坑 | 表现 | 正解 |
|---|---|---|
动态 import() | 标准动态导入不被支持 | 延迟加载用 require.async(),且仅限分包 |
| app.json 的 permission | 写 scope.record 报「无效的 app.json permission」 | permission 只接受位置类;录音授权用运行时 wx.authorize |
| 切后台断网 | 后台 5 秒 TCP 被系统掐断 | onShow 里触发重连,不指望后台保活 |
| 路径别名 | tsconfig 的 paths 模拟器不认 | 全项目相对路径 |
最后一条值得多说一句:既然 moduleResolution: "node" 和小程序
解析器不一致,理论上也可以把 tsconfig 改成更严格的解析模式来提前暴露问题。
但更诚实的做法是承认约定无法被类型系统完全表达,
把它写进文档、写进 code review 清单——因为这类坑的本质是「环境差异」,
而环境差异只能靠见识过一次来免疫。
05复盘:把「环境差异」当成一等公民
这个坑的成本其实不高——找到原因只要半小时。真正贵的是它的隐蔽性: 如果不是第一天生效的严格导入约定拦住了后续所有代码, 这个错误会以各种变体反复出现。
所以我现在会这样总结小程序开发的工具链认知:
- tsc 绿 ≠ 运行时对。类型检查器按自己的解析规则工作, 它不知道你的目标运行时有多笨。
- 连锁报错要看第一条。app.js 一崩,后面全是余震; 从最后一条开始查是浪费生命。
- 环境差异要落成书面约定,并且放在规范里离代码最近的位置—— 恰好就在「怎么写 import」那一节。
- 关于本文
- 整理自「一语控物」项目的真实踩坑记录 (docs/04-开发规范与约定.md §2.2 的出处)。
- 2026.10.23 整理
- 这篇最想留下的不是「要写 /index」这个知识点,而是它背后的模式: 多环境工具链里,最严格的那个解析器决定代码怎么写。 TS 和 Jest 都宽容,但宽容是它们的自由,不是代码的自由。
留言
正在载入留言…