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

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

• 云端运行正常

• 本地目录里明明存在 uni-id-common

• require 相对路径也试过，仍然报错

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

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

一、问题现象

1. 本地报错

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

2. 云端正常

• token 能校验

• uid 能获取

• 云端日志无模块报错

这说明：

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

二、目录结构确认

项目结构如下：

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

同时项目里还有：

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 里写：

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

解释：

• vip 和 common 是同级目录

• file:../common/uni-id-common 指向真实运行的公共模块目录

• 本地调试时会把它安装为依赖

然后：

1. 右键 vip → 安装依赖

2. 重新运行本地云对象

问题直接消失。

---

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

例如：

"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 少了一行。