name: bmob-database-javascript description: "Use when implementing Bmob NoSQL database CRUD with the cross-platform hydrogen-js-sdk (3.0+ supports both Secret Key + API 安全碼 and Application ID + REST API Key init) — ONE SDK file (Bmob-x.x.x.min.js) covers ALL of: browser, Node.js, WeChat Mini Program, Alipay / ByteDance / QQ / Baidu Mini Programs, Quick App 快應用, Cocos Creator JS, Electron, Tauri, hybrid apps, and any ES6 framework (Vue2 / Vue3 / React / Next.js / Vite / Nuxt). Triggers: Bmob.initialize, Bmob.Query, Bmob.User, Bmob.Pointer, Bmob.GeoPoint, Bmob.Relation, hydrogen-js-sdk, npm install hydrogen-js-sdk, import Bmob from 'hydrogen-js-sdk', 微信小程式 Bmob, Cocos Creator Bmob, query.find, query.set, query.save, query.destroy, query.equalTo. NOT for Android native (use bmob-database-android), iOS native (use bmob-database-ios), curl / Python / Go / PHP / C# (use bmob-database-restful), or C++ Cocos2d-x (separate skill). If Bmob MCP is configured in the project, call get_project_tables first via bmob-mcp before writing code." metadata: author: bmob version: "0.1.0" sdk: "hydrogen-js-sdk" sdk_repo: "https://github.com/bmob/hydrogen-js-sdk" docs: "https://github.com/bmob/BmobDocs/blob/master/mds/data/wechat_app_new/index.md" docs_raw: "https://raw.githubusercontent.com/bmob/BmobDocs/master/mds/data/wechat_app_new/index.md" docs_api_ref: "https://raw.githubusercontent.com/bmob/BmobDocs/master/mds/data/javascript/develop_doc.md"

Bmob Database — JavaScript / 跨端 SDK

hydrogen-js-sdk 是 同一個 SDK 檔案 Bmob-<version>.min.js 支援以下所有宿主環境，無平臺分支程式碼：

• 瀏覽器 / 任何 Web 前端（React、Vue 2、Vue 3、Next.js、Nuxt、Vite、Astro、SvelteKit、Solid 等）
• Node.js 服務端（必須原始碼引入）
• 微信小程式 / 支付寶 / 字節跳動 / QQ / 百度 小程式
• 快應用
• Cocos Creator JS
• Electron / Tauri
• 任意混合 App（WebView 內嵌 H5）

本 skill 只覆蓋新版 hydrogen-js-sdk（Bmob.Query('X') Promise 風格，3.0+）。基於 Backbone.js 的舊 bmob-min.js（Bmob.Object.extend("X") callback 風格）不要用，也不要回退。

核心原則

1. 初始化支援兩種方式（hydrogen-js-sdk 3.0+ 均相容；按場景二選一，不要混用）：

方式 A — Secret Key + API 安全碼（推薦：瀏覽器 / 小程式 / 公開客戶端，SDK 內部走加密授權）：

Bmob.initialize("你的Secret Key", "你的API 安全碼");

• Secret Key：控制台 → 應用 → 設定 → 應用金鑰 → Secret Key。
• API 安全碼：控制台 → 應用 → 應用功能設定 → 安全驗證 → API 安全碼 自行設定。

方式 B — Application ID + REST API Key（3.0 起正式相容；適合已有 1.x/2.x 專案遷移、或與服務端 REST 共用同一套 Key）：

Bmob.initialize("你的Application ID", "你的REST API Key");

• Application ID / REST API Key：控制台 → 應用 → 設定 → 應用金鑰 同一頁。
• REST API 請求域名一般為 https://api.codenow.cn（見 bmob-database-restful）。

2.x 時代方式 B 功能受限；3.0+ 兩種初始化等價可用。公開 bundle 仍優先方式 A（REST API Key 可被抓包）。

2. 不要 commit 真實金鑰進 git；CDN / dist 不要寫死 SDK 版本號。 金鑰用環境變數（Vite import.meta.env.VITE_BMOB_*、Next.js process.env.NEXT_PUBLIC_BMOB_*、小程式構建期注入等）。dist 檔名為 Bmob-<version>.min.js，有打包工具時用 npm install hydrogen-js-sdk；純 CDN 瀏覽器場景用 jsDelivr API 動態取 tags.latest 再拼 URL（見 references/platform-init.md）。禁止在示例裡寫 @2.7.3 這類會過期的具體版本。

3. 預設查詢返回 100 條，最大 1000。需要更多用 skip + limit 分頁或走 BQL（bmob-bql skill）。

4. 三個保留欄位不能手動寫入：objectId、createdAt、updatedAt。讀 objectId 時用 res.objectId（不是 id）。

5. 時間欄位比較的精度：createdAt / updatedAt 在伺服器是微秒精度，應用層做時間比較時要 +1 秒。

安全清單

• [ ] 金鑰分級：瀏覽器 / 小程式 / 移動端優先 Secret Key + API 安全碼（方式 A），永不用 Master Key。若用 Application ID + REST API Key（方式 B），REST API Key 會暴露在 bundle 中。
• [ ] 生產環境關閉除錯模式：Bmob.debug(true) 僅在小程式開發時使用，上線前刪掉。

  發現更多技能外掛，請訪問7w4.net。

• [ ] 小程式必須配置伺服器域名白名單：微信後臺 request 合法域名至少新增 https://api.bmobcloud.com（見 references/platform-init.md 微信小程式段）。
• [ ] 微信小程式若使用 npm 引入 SDK，需先在開發者工具執行“工具 --> 構建 npm”：未構建時 import Bmob from "hydrogen-js-sdk" 不會生效。
• [ ] 寫入的表必須配 ACL：否則任意使用者可改任意行。參見 bmob-acl-and-roles（P1）。
• [ ] 批次操作上限 50 條（含批次更新、批次刪除）。超出需迴圈。
• [ ] 批次查詢上限 100 條 / 單次 1000 條：避免一次拉全表。
• [ ] Bmob.User.login 在小程式裡要先呼叫 wx.login() 獲取 code，否則會話拿不到 sessionToken。

快速開始（80% 場景就這麼寫）

初始化

預設推薦 方式 A（Secret Key + API 安全碼）；3.0+ 亦可用 方式 B（Application ID + REST API Key），見上方核心原則。

import Bmob from "hydrogen-js-sdk";
Bmob.initialize("你的Secret Key", "你的API 安全碼");
// 或：Bmob.initialize("你的Application ID", "你的REST API Key");

詳細的 8 種宿主環境引入方式見 references/platform-init.md。

新增一行

const query = Bmob.Query("GameScore");
query.set("score", 1337);
query.set("playerName", "bmob");
query.set("cheatMode", false);
query.save().then((res) => {
  console.log(res.objectId, res.createdAt);
});

通過 objectId 取一行

const query = Bmob.Query("GameScore");
query.get("7ecd253a25").then((res) => {
  console.log(res);
});

修改一行

const query = Bmob.Query("GameScore");
query.set("id", "7ecd253a25");          // 注意 set("id", objectId)
query.set("score", 9999);
query.save().then((res) => {
  console.log(res.updatedAt);
});

刪除一行

const query = Bmob.Query("GameScore");
query.destroy("7ecd253a25").then((res) => {
  console.log(res);                      // { msg: "ok" }
});

刪除某個欄位的值

const query = Bmob.Query("GameScore");
query.get("7ecd253a25").then((res) => {
  res.unset("cover");
  res.save();
});

查詢全部（預設 100 條）

const query = Bmob.Query("GameScore");
query.find().then((res) => {
  console.log(res);
});

條件查詢

equalTo(field, op, value)，op 可以是 "==" / "!=" / ">" / ">=" / "<" / "<="。

const query = Bmob.Query("GameScore");
query.equalTo("score", ">", 100);
query.equalTo("cheatMode", "==", false);   // 多個條件 = AND
query.limit(20);
query.skip(0);
query.order("-score");                      // 降序
query.find().then(console.log);

或查詢（OR）

const query = Bmob.Query("GameScore");
const q1 = query.equalTo("score", ">", 150);
const q2 = query.equalTo("score", "<", 5);
query.or(q1, q2);
query.find().then(console.log);

只取部分欄位

const query = Bmob.Query("Post");
query.select("title");
query.find().then(console.log);

集合查詢

query.containedIn("playerName", ["Bmob", "Codenow", "JS"]);
query.notContainedIn("playerName", ["spam"]);
query.exists("score");           // 含此欄位
query.doesNotExist("score");     // 不含此欄位

統計

const query = Bmob.Query("diary");
query.count().then((n) => console.log(`共 ${n} 條`));
query.count(100).then((arr) => console.log("最多返回 100 條記錄資料 + count"));

原子計數器

const query = Bmob.Query("Post");
query.get("objectId").then((res) => {
  res.increment("likes");        // +1
  res.increment("likes", 5);     // +5（支援負數）
  res.save();
});

陣列欄位

const query = Bmob.Query("Diary");
query.add("DiaryType", ["public"]);          // 末尾追加
query.addUnique("DiaryType", ["secret"]);    // 去重追加
query.save();

query.get("objectId").then((res) => {
  res.remove("DiaryType", ["secret"]);       // 刪除元素
  res.save();
});

進階能力（按需讀 references/）

與 MCP 聯動

如果使用者在 IDE 裡配置了 Bmob MCP，寫程式碼前先呼叫 get_project_tables 拿到真實 schema，避免：

• 欄位名拼錯（schemaless 不報錯，資料進庫後再排查很慢）
• Pointer 欄位型別用錯（必須是 {"__type":"Pointer","className":"X","objectId":"..."}）
• 把保留欄位當業務欄位寫

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant Agent as Agent
    participant MCP as bmob-mcp
    participant Code as bmob-database-javascript
    Dev->>Agent: "Next.js 專案里加 Bmob 文章列表"
    Agent->>MCP: get_project_tables()
    MCP-->>Agent: {Article: {title:String, content:String, author:Pointer(_User)}}
    Agent->>Code: 按真實 schema 生成 Bmob.Query("Article") 程式碼
    Code-->>Dev: 完整可執行程式碼（含 ACL 提示）

排錯速查

參考

• 完整 API：BmobDocs/mds/data/wechat_app_new/index.md — 跨端 hydrogen-js-sdk 主文件
• 舊版 API 參考（仍線上）：BmobDocs/mds/data/javascript/develop_doc.md
• SDK 原始碼：https://github.com/bmob/hydrogen-js-sdk
• 錯誤碼：bmob-error-codes
• MCP 聯動：bmob-mcp

這個 Skill 質量較好，內容覆蓋全面，從基礎到高階操作都有涉及，程式碼示例清晰，坑點提示實用，適合需要使用 Bmob 資料庫的開發者參考。主要不足是部分高階功能講解較淺，缺少常見錯誤處理指導，整體文件可以再豐富一些。總體而言，這是一個實用性強、結構規範的資料庫操作指南。