UniCloud 本地调试云对象报 Cannot find module ‘uni-id-common‘ 的排查与解决

最近在做会员体系时，vip 云对象本地调试一直报错：

写法完也是按照官方文档写的,但诡异的是：

云端运行正常
本地目录里明明存在 uni-id-common
require 相对路径也试过，仍然报错

折腾了很久才发现根因，其实是 本地云对象依赖解析机制和云端不同。

这篇记录一下完整排查过程和最终解决方案。

一、问题现象

1. 本地报错

javascript 复制代码

Error: Cannot find module 'uni-id-common'

2. 云端正常

token 能校验
uid 能获取
云端日志无模块报错

这说明：

代码没问题，是本地运行环境的依赖解析有问题。

二、目录结构确认

项目结构如下：

javascript 复制代码

uniCloud-aliyun/
  cloudfunctions/
    common/
      uni-id-common/
    vip/

同时项目里还有：

javascript 复制代码

uni_modules/
  uni-id-common/
    uniCloud/cloudfunctions/common/uni-id-common/

这两者不是同一个运行路径。

三、为什么云端能跑，本地不行？

核心原因：

本地调试云对象时，Node 只会解析当前云函数目录的 package.json 依赖，不会自动把 cloudfunctions/common 加入模块搜索路径。

而云端运行时：

云空间公共模块会被自动识别
require('uni-id-common') 能正常解析

也就是说：

云端有"公共模块自动注入机制"，本地没有。

四、错误的排查方向

我一开始做了很多无效尝试：

改相对路径 ../common/uni-id-common
用 __dirname 向上查找
动态 require
确认文件存在
打印运行目录

都没解决。

原因很简单：

本地云对象运行时，是基于自身 package.json 安装依赖的，不会帮你解析公共模块目录。

五、真正的解决方案

关键在于：

把 uni-id-common 显式写入 vip 云对象的 package.json 依赖。

正确写法（推荐）

在 vip/package.json 里写：

javascript 复制代码

{
  "name": "vip",
  "dependencies": {
    "uni-id-common": "file:../common/uni-id-common"
  },
  "extensions": {
    "uni-cloud-jql": {}
  }
}

解释：

vip 和 common 是同级目录
file:../common/uni-id-common 指向真实运行的公共模块目录
本地调试时会把它安装为依赖

然后：

右键 vip → 安装依赖
重新运行本地云对象

问题直接消失。

六、为什么之前写成 uni_modules 路径也能用？

例如：

javascript 复制代码

"uni-id-common": "file:../../../uni_modules/uni-id-common/uniCloud/cloudfunctions/common/uni-id-common"

这种方式也可以。

但不推荐，因为：

依赖的是插件源码目录
未来插件升级可能路径变化
和云端真实部署结构不一致

最稳的是依赖 cloudfunctions/common 下那份。

七、本质总结

这个坑的本质是：

本地调试云对象 = 标准 Node 运行环境

云端运行云对象 = 带有公共模块解析机制的特殊环境

不要把"云端自动识别公共模块"当成理所当然。

在本地调试时：

每个云函数就是一个独立 Node 项目
必须在 package.json 里声明依赖
公共模块不会自动加入解析路径

八、经验总结

1. 云对象本地报模块错误，优先检查：

当前云函数的 package.json
是否显式声明依赖
是否执行了安装依赖

2. 不要盲目怀疑目录结构

文件存在 ≠ Node 能解析

Node 只认：

当前函数的 node_modules
package.json 依赖
明确 file 路径

3. dev/prod 与本地/云端是三套环境

本地调试
云端 dev
云端 prod

模块解析机制不完全一致。

九、最终结论

这个问题不是代码逻辑问题，而是：

本地云对象依赖路径未更新。

一句话总结：

云端能跑 ≠ 本地能跑

本地调试必须显式声明依赖。

这类问题的最大浪费在于：

你会怀疑 token
怀疑 uid
怀疑数据库
怀疑事务
怀疑权限

但实际上只是 package.json 少了一行。