Nuxt 3项目使用RxDB的PouchDB适配器报错如何解决？

根因说明 #

PouchDB生态包存在长期未修复的ESM/CommonJS模块互操作问题，Vite默认的模块解析逻辑无法正确处理pouchdb-errors等包对CommonJS模块的默认导入语句；错误配置vite.define替换全局global标识符时，会误替换Nuxt路由文件内的global配置属性，直接触发构建失败。

正确配置步骤 #

1. nuxt.config.ts 配置 #

直接替换对应配置段即可，注意不要遗漏任何依赖项：

export default defineNuxtConfig({
  ssr: false,
  build: {
    transpile: [
      'rxdb',
      'rxdb/plugins/pouchdb',
      'pouchdb-browser',
      'pouchdb-utils',
      'pouchdb-errors',
      'pouchdb-adapter-idb',
      'pouchdb-adapter-http'
    ]
  },
  vite: {
    define: {
      // 禁止配置为{}，必须指向浏览器全局对象
      global: 'globalThis',
      'process.env': {}
    },
    optimizeDeps: {
      // 预构建所有相关依赖，解决dev模式下的模块解析错误
      include: [
        'pouchdb-browser',
        'pouchdb-utils',
        'pouchdb-errors',
        'pouchdb-adapter-idb',
        'pouchdb-adapter-http',
        'inherits'
      ]
    },
    resolve: {
      alias: {
        // 强制引用浏览器端PouchDB入口，避免误拉取Node端依赖
        pouchdb: 'pouchdb-browser'
      }
    }
  }
})

2. RxDB插件写法调整 #

插件必须加客户端运行判断，即使开启ssr: false，Nuxt构建阶段仍会执行部分服务端逻辑，要避免该阶段加载浏览器专属的PouchDB适配器：

// plugins/rxdb.ts
import { addPouchPlugin, createRxDatabase, getRxStoragePouch } from 'rxdb/plugins/pouchdb'
import idbAdapter from 'pouchdb-adapter-idb'

if (process.client) {
  addPouchPlugin(idbAdapter)
}

export default defineNuxtPlugin(async () => {
  if (!process.client) {
    return { provide: { db: null } }
  }

  const db = await createRxDatabase({
    name: 'test',
    storage: getRxStoragePouch('idb')
  })

  return {
    provide: { db }
  }
})

关键注意事项 #

• 配置修改后必须先清理缓存：删除根目录.nuxt文件夹、node_modules/.vite文件夹后再启动开发服务，旧的预构建缓存会导致配置完全不生效，这是多数人调试无效的核心原因。
• 不要把global定义为空对象：该配置会全局替换所有代码中名为global的标识符，包括Nuxt路由配置里的global属性，直接触发非JS文件导入的语法错误。
• transpile列表不能只加pouchdb-browser和pouchdb-utils，必须把rxdb本身、所有用到的pouchdb适配器、pouchdb核心依赖全部加入，否则Vite仍会加载未经过CommonJS兼容转译的异常模块。

内容的提问来源于stack exchange，提问作者HypeWolf