PouchDB 6.0.0 升级指南：移除旧 API、收紧依赖与视图沙箱化的全面解读

• 数据库
• 数据同步

本文基于仓库文档 docs/posts/2016-09-05-pouchdb-6.0.0.md 撰写，围绕 PouchDB 6.0.0（代号 "Labour Day"）这一破坏性版本展开：它把 5.4.0 中标记弃用的 API 正式删除，移除了extras内部接口与 SQLite 插件的自动检测，让leveldown成为 Node 环境的必需依赖，并将视图/过滤函数执行纳入'use strict'沙箱。读完本文，你将得到一份可直接对照执行的 5.x → 6.0.0 迁移清单，并理解这些变更背后的多包架构与安全设计动机。

版本背景：从 5.4.0 弃用到 6.0.0 移除

PouchDB 6.0.0 是一次"清理型"主版本。早在 5.4.0 发布说明 中，团队就预告了多项弃用（deprecation）：db.put(doc, id, rev)签名、异步构造函数回调、以及PouchDB.utils/PouchDB.ajax/PouchDB.Errors等未文档化 API。到了 6.0.0，这些被弃用的能力被正式移除，同时附带了大量 bugfix、文档修订与通用改进。

理解这次移除，需要先理解 5.4.0 引入的多包（monorepo）架构。正如 Introducing PouchDB custom builds 所描述的，PouchDB 从单一巨型包拆分为pouchdb-core+ 一系列pouchdb-*插件包，通过PouchDB.plugin()组合出不同预设（preset），例如pouchdb-browser、pouchdb-node、pouchdb-http。6.0.0 的多数"移除"正是这一架构演进的收尾动作：内部extras子路径被独立包取代，可选原生依赖被收敛为必需依赖。当前仓库根目录的 package.json 中，leveldown、memdown、localstorage-down等均为直接依赖，也印证了这一收敛方向。

一、正式移除的功能清单

6.0.0 的破坏性变更全部来自 5.4.0 预告的弃用项，逐一迁移即可平滑升级。

1. 移除db.put(doc, id, rev)三参数签名

旧写法把_id和_rev作为独立的第二、第三个参数传入：

// 6.0.0 之前（已弃用） db.put({data: 'foo'}, 'myid', '2-xxx');

新写法要求把_id和_rev直接放进文档对象本身：

db.put({_id: 'myid', _rev: '2-xxx', data: 'foo'});

这一 API 自 5.4.0 起每次使用都会打印警告，6.0.0 彻底删除。升级时只需搜索代码中所有db.put(的三参数调用并改写为单对象形式。

2. 构造函数改为无状态：移除new PouchDB(dbName).then与回调

6.0.0 之前，构造函数返回的对象带有异步初始化语义，既可以.then()等待就绪，也支持回调风格：

// 6.0.0 之前（已弃用） new PouchDB('mydb').then(function (db) { /* ... */ }); // 或回调风格（同样被移除） new PouchDB('mydb', function (err) { // 异步初始化完成后（或出错时）被调用 });

6.0.0 起构造函数完全无状态：new PouchDB(dbName)立即返回可用的数据库实例，不再需要等待异步 setup。如果你确实需要验证数据库能否完成初始化（例如检测本地存储是否可用），请改用显式的info()探测：

var db = new PouchDB('mydb'); db.info() .then(function () { // 数据库已就绪 }) .catch(function (err) { // 初始化失败，可在此处理 });

注意，回调风格new PouchDB(dbName, function (err) {})同样不再支持，必须统一改为 Promise 风格 +info()。

3. 移除 WebSQL 对 SQLite 插件的自动检测

在 Cordova 环境中，旧的 WebSQL 适配器会自动检测 SQLite 插件（cordova-plugin-sqlite）并切换底层实现。6.0.0 移除了这一隐式行为，避免"自动魔法"带来的不确定性。如果你在 Cordova 中需要 SQLite 存储，请显式使用社区维护的独立插件：

npm install pouchdb-adapter-cordova-sqlite

然后通过标准的PouchDB.plugin()机制注册使用（该插件为第三方包，不属于本仓库内置模块）。

4. 移除extrasAPI，改为独立 npm 包

require('pouchdb/extras/xxx')这类子路径在 6.0.0 全部失效，对应能力被拆分为独立包。官方给出的对照关系如下：

带*的适配器包在安装后还必须显式注册为插件才能生效，例如：

var PouchDB = require('pouchdb-core'); PouchDB.plugin(require('pouchdb-adapter-memory')); var db = new PouchDB('mydb', {adapter: 'memory'});

这一注册模式在当前仓库中处处可见，例如 tests/unit/test.memory-adapter.js 正是用PouchDB.plugin(memoryAdapter)挂载内存适配器后运行测试的。更完整的适配器清单与用法，可参阅 docs/custom.md（其中pouchdb-adapter-leveldb、pouchdb-adapter-memory也注明了后续版本（10.0.0 起弃用、11.0.0 移除）的迁移预告，升级时值得一并关注）。

注意一个细节：非 HTTP 适配器的plugin()注册顺序会影响适配器的选择优先级。例如希望按 "IndexedDB → WebSQL → LocalStorage → 内存" 的次序回退，就必须按该顺序依次.plugin()，这与 Introducing PouchDB custom builds 中给出的示例一致。

5. 移除 HTTP 适配器的getUrl()与getHeaders()

这两个 API 此前从未被文档化，属于内部实现细节。6.0.0 将其删除：

• getUrl()的替代方案是直接读取db.name。对 HTTP/HTTPS 适配器而言，db.name就是完整的数据库 URL（例如'http://127.0.0.1:5984/mydb'），因此获取 URL 只需db.name即可；
• getHeaders()官方明确不提供替代方案，需要自定义请求头的场景应改走其他途径。

6. 移除node-websql依赖与optionalDependencies，leveldown成为必需

此前leveldown和websql都是"可选依赖"（optionalDependencies），只有在对应场景才会安装。6.0.0 起：

• websql从主包中彻底移除，Node 端如需 WebSQL 语义，改用独立的pouchdb-adapter-node-websql包；
• leveldown从可选变为必需依赖，npm install pouchdb（Node 完整包）必然安装 LevelDB。

如果希望避免安装leveldown（例如原生模块在部分操作系统上编译耗时甚至失败），官方给出两条替代路径：

• 只在浏览器使用：安装pouchdb-browser预设，它不包含任何 Node 端依赖；
• 只需要内存数据库：安装pouchdb-memory（或pouchdb-core+pouchdb-adapter-memory组合）。

其他更精细的裁剪场景（例如"只要 HTTP 适配器"的pouchdb-http预设），统一参考 docs/custom.md 的 Custom Builds 说明。从当前仓库 package.json 可以看到，leveldown（6.1.1）与memdown（1.4.1）均已列入顶层直接依赖，正是这一"去可选化"策略的延续。

7. 视图与过滤函数进入沙箱执行

这是 6.0.0 中偏"安全语义"的变更：map/reduce 的视图函数与复制/变更流的过滤函数，现在统一在'use strict'环境下执行；在 Node 端，还会运行在一个**沙箱（sandbox）**中。

这意味着：

• 如果你的视图/过滤函数依赖非严格模式行为（例如未声明的隐式全局变量、with语句、arguments.callee等），升级后将直接报错，必须改写为严格模式兼容的代码；
• 在 Node 中，函数无法再访问沙箱外的全局状态，所有依赖都必须显式传入或通过闭包在函数内部处理；
• 从源码结构看，这是为了减少"用户函数执行"对 PouchDB 内部环境的副作用、提升健壮性的防御性设计，同时也让行为在浏览器与 Node 两端保持一致。

迁移建议：为所有视图/过滤函数显式声明变量、避免依赖宿主全局对象，并保证纯函数化（只依赖doc入参和emit()）。

二、Bugfix 亮点：稳定性与内存治理

6.0.0 附带了一批围绕"错误处理、内存释放、监听器泄漏"的修复，对生产环境意义重大，可归纳为几类：

错误不再被吞掉（#5214）：此前部分路径会静默吞掉异常（"squelching errors"），6.0.0 起这些错误会正常向上抛出，便于定位问题——同时也意味着升级后可能暴露出之前被掩盖的异常，建议在升级后跑一遍完整的错误路径测试。

附件与内存治理：限制并发附件请求数量（#3962），避免短时间发出过多请求；修复附件 md5sum 计算导致的内存泄漏（#4632）；AJAX 请求更快释放内存（#5441）；修复二进制检查前未判断ArrayBuffer是否存在导致的异常（#5527）。

监听器泄漏与事件治理：移除变更监听器的无界累积（#5402）、不泄漏 change 监听器（#5450）、修复事件发射器泄漏（5.4.0 的 #4444 修复在 6.0.0 中得到延续），并区分"校验类错误"与"非校验类错误"（#5172）。

复制与检查点：当last_seq未变化时不再更新检查点（#5379），减少无谓写入；对远程数据库的检查点写入改用PUT而非POST（#5443），以兼容 CouchDB 的幂等语义；复制中的bulkDocs()开始支持options.timeout（#5584）。这些逻辑对应到本仓库，可结合复制检查点相关的单元测试 tests/unit/test.checkpointer.js 深入理解。

HTTP/URL 细节：当opts.prefix是 URL 时对数据库名进行正确编码（#5574）；修复xhr.response === null场景（#5491）；PouchDB.plugin()在收到错误类型或空对象时抛出更清晰的错误（#5471）——仓库集成测试 tests/integration/test.basics.js 中就有针对 #5471 与 "PouchDB.plugin()resets defaults" 的回归用例，可作为插件 API 行为的参考。

Map 函数只调用一次（#4967）：修复了视图 map 函数在某些场景下被重复调用的问题，属于查询正确性修复。

三、文档与网站改进

6.0.0 的文档工作同样密集，其中与开发者直接相关的有：

• 为官网新增ServiceWorker 支持（#5304），配合离线场景使用——当前仓库中仍保留着 docs/serviceWorker.js.liquid 与 docs/manifest.appcache.liquid 等网站相关模板；
• 在 map 函数文档中补充了emit()的用法说明（#5449），涉及视图编写规范；
• 修正changes()文档措辞（#5570），并在示例中补充last_seq字段（#5597），便于理解变更流的响应结构；
• 移除破坏 Markdown 渲染的空白字符（#5359）、修正 typo（#5556/#5594）、统一标题的 Markdown 化（#5412）、更新 ISSUE_TEMPLATE（#5602）等。

这些文档修订虽然不改变运行行为，但对 API 的准确理解与检索有实际价值。

四、6.0.0 升级自检清单

综合以上变更，从 5.x 升级到 6.0.0 时建议按如下顺序排查：

1. 全局搜索三参数db.put(doc, id, rev)，改写为db.put({_id, _rev, ...})；
2. 删除所有new PouchDB(...).then(...)与构造回调，改用db.info()探测就绪状态；
3. 替换全部pouchdb/extras/...导入为对应的独立包，并对适配器显式PouchDB.plugin()注册；
4. 检查 HTTP 适配器代码：getUrl()改用db.name，删除getHeaders()调用；
5. 审视package.json依赖：确认leveldown已作为直接依赖安装；若想避免它，改用pouchdb-browser或内存适配器组合；
6. Cordova 项目：移除对 SQLite 插件自动检测的隐式依赖，显式引入pouchdb-adapter-cordova-sqlite；
7. 为所有视图/过滤函数过一遍严格模式：去掉隐式全局、with等非严格写法，确保在沙箱中可运行；
8. 回归测试错误路径：由于"不再吞错"，升级后可能暴露旧版本掩盖的异常，建议重点跑复制、变更流、视图查询的测试。

需要了解 5.4.0 引入的多包/自定义构建背景，可继续阅读 Introducing PouchDB custom builds 与 docs/custom.md；想验证升级后的行为，仓库 tests/unit 与 tests/integration 下的测试套件（npm run test-unit与npm run test-node，见 package.json）是很好的行为参照。

• 数据库
• 数据同步