JG-JCore 和 JG-JPush 必须成对安装并正确配置：先装 JG-JCore 再装 JG-JPush，AppKey 需填入插件专属配置块，包名须与极光后台一致，真机调试必须使用自定义基座，并在 onLaunch 中初始化且加 #ifdef APP-PLUS 条件编译。
jg-jcore 和 jg-jpush 必须同时安装，缺一不可——只装 jg-jpush 会报“找不到 jcore 依赖”，因为极光 sdk 自 3.x 起已拆分为基础服务（jcore）和推送功能（jpush）两个独立模块。
JG-JCore 和 JG-JPush 插件必须成对安装
- HBuilderX 插件市场里搜不到单个
JG-JPush是正常现象：它默认隐藏未满足依赖的插件 - 正确操作顺序：
- 先搜索并安装
JG-JCore - 再搜索并安装
JG-JPush
- 先搜索并安装
- 安装完成后，务必进
manifest.json→ 【APP原生插件配置】→ 勾选这两个插件 → 点击【确定】 - 若项目已有
nativePlugins/目录（比如之前做过离线打包），请手动删除旧版冲突插件文件夹，否则可能 init 失败但无任何错误提示
manifest.json 中 AppKey 必须填在插件专属配置块里
填错位置是真机调试失败最常见原因。不是填在 “Android 设置” 或 “iOS 设置” 下，而是填在插件自己的 JSON 配置中：
{
"name": "JG-JPush",
"android": {
"JPUSH_APPKEY_ANDROID": "你的Android AppKey",
"JPUSH_CHANNEL": "developer-default"
},
"ios": {
"JPUSH_APPKEY_IOS": "你的iOS AppKey"
}
}
-
JPUSH_APPKEY_ANDROID和JPUSH_APPKEY_IOS是两个独立字段，不能混用 - 包名（
packagename）必须与极光后台创建应用时填写的完全一致（含大小写），Android 包名路径为：manifest.json→app-plus→distribute→android→packagename -
JPUSH_CHANNEL建议只用英文、数字或下划线，避免中文、空格、特殊符号，否则部分厂商通道会静默失败
真机运行必须用自定义调试基座
uni.requireNativePlugin("JG-JPush") 在标准调试基座中返回 undefined，所有后续调用都会失效。
- 正确做法：HBuilderX → 【发行】→ 【原生App-制作自定义调试基座】→ 选择对应平台（Android/iOS）→ 等待完成
- 制作完成后，手机上必须卸载旧调试 App，再点【运行到手机】，否则仍走旧基座
- 首次运行时，控制台看到
jpush连接 true才算连上；如果一直false，优先检查：网络是否通畅、厂商通道是否开启、是否被国产 ROM 后台限制（如小米、华为的自启动/电池优化白名单）
App.vue 中初始化代码必须放在正确作用域且带平台判断
- 初始化不能写在
methods或onShow里，必须在onLaunch生命周期中执行 - 必须加
#ifdef APP-PLUS条件编译，否则 H5 或小程序环境会报错 - 示例片段（仅核心逻辑）：
// #ifdef APP-PLUS
var jpushModule = uni.requireNativePlugin("JG-JPush");
export default {
onLaunch() {
console.log('App Launch');
jpushModule.init();
// iOS 需主动申请通知权限
if (uni.getSystemInfoSync().platform === "ios") {
jpushModule.requestNotificationAuthorization(() => {});
}
}
}
// #endif
容易被忽略的是：iOS 的通知权限申请必须在 init() 之后、且不能晚于用户首次触发时机；Android 则需额外处理 isNotificationEnabled 检查，否则部分新机型（如 ColorOS 14）可能默认关闭通知开关。
