# @existdb/node-exist 中文文档

规范地址：https://npmcn.com/package/%40existdb/node-exist/

版本：8\.0\.0
npm 元数据更新时间：2026-09-12T20:53:14.536Z
中文译文更新时间：2026-11-14T03:37:08.743Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40existdb/node-exist
原文对照：https://npmcn.com/package/%40existdb/node-exist/?lang=original
项目主页：https://github.com/eXist-db/node-exist#readme
源码仓库：https://github.com/eXist-db/node-exist

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：75.9 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- 首次发布：2018-07-25T22:43:16.177Z
- 最新版本发布：2026-09-12T20:53:14.243Z
- 近 30 天下载量：3000（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 3 个）

## 中文简介

与 eXist DB 的 XML- RPC API 基于承诺的交互

## 安装

```sh
npm install @existdb/node-exist
```

也可以使用：`pnpm add @existdb/node-exist`、`yarn add @existdb/node-exist`、`bun add @existdb/node-exist`

## README

# 节点性别

![semantic release status](https://github.com/exist-db/node-exist/actions/workflows/semantic-release.yml/badge.svg) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)

主要是浅薄的包装 [eXist 的 XML- RPC API](http://exist-db.org/exist/apps/doc/devguide_xmlrpc.xml) 财务报告和审定财务报表 [(原始内容存档于2013-10-12). eXist's REST API](https://exist-db.org/exist/apps/doc/devguide_rest.xml)。 。 。 . 试图将名词翻译为节点世界. 用承诺.

-   [安装](https://npmcn.com/package/%40existdb/node-exist/#readme-install)
-   [使用](https://npmcn.com/package/%40existdb/node-exist/#readme-use)
-   [连接选项](https://npmcn.com/package/%40existdb/node-exist/#readme-connection-options)
-   [构成部分](https://npmcn.com/package/%40existdb/node-exist/#readme-components)
-   [命令行脚本](https://npmcn.com/package/%40existdb/node-exist/#readme-command-line-scripts)
-   [测试](https://npmcn.com/package/%40existdb/node-exist/#readme-test)
-   [路线图](https://npmcn.com/package/%40existdb/node-exist/#readme-roadmap)
-   [兼容性](https://npmcn.com/package/%40existdb/node-exist/#readme-compatibility)
-   [免责声明](https://npmcn.com/package/%40existdb/node-exist/#readme-disclaimer)

## 安装

```sh
npm install @existdb/node-exist
```

**注:** 如果您正在寻找命令行客户端, 请查看 [页:1](https://github.com/eXist-db/xst)

## 使用

除了eXist-db的XML-RPC API外,您现在还可以选择 利用它的潜力. 这样就可以为任何特定任务选择最佳工具. 两个API都用于组合 [上传示例](https://npmcn.com/package/%40existdb/node-exist/spec/examples/exist-upload)。 。 。 .

**注:** 这一一揽子措施现在仅是无害环境管理.

### 资源

状态:不稳定

**注:** eXist-db的REST-API有其方法和现有备选方案 不同的情况可能不同。 特别是能力 下载 QQuery 文件的源代码 默认禁止( e)`_source=yes` 只有在启用于 `descriptor.xml`) (中文(简体) ). 详细情况 `options` 请参看 [REST-API 文档](https://exist-db.org/exist/apps/doc/devguide_rest.xml)

首先,我们需要一个休息的例子.

```js
import { getRestClient } from '@existdb/node-exist'
const rc = getRestClient()
```

更多信息另见 [连接选项](https://npmcn.com/package/%40existdb/node-exist/#readme-connection-options)。 。 。 .

返回的 HTTP 客户端有 4 个方法

-   `post(query, path[, options])`: 执行 `query` 二、在增进和保护人权方面 `path`。 。 。 . 这个 `query` 预计将是一个 QQury 主模块, 并将被包裹在存在的 XML- flagment 中.
    
    ```js
    const { bodyText } = await rc.post('count(//p)', '/db')
    console.log(bodyText)
    ```
    
-   `put(data, path)`: 在数据库中创建资源. 如果路径中的子集缺失,它们将被创建给你. 服务器将使用状态代码400, Bad Request, 为不.. 组成 XML 资源。 在这种情况下,尸体包含一个详细的 描述验证错误.
    
    ```js
    await rc.put('<root />', '/db/rest-test/test.xml')
    ```
    
-   `get(path [, options][, writableStream])`:从数据库读取数据. 响应机构将包含资源内容或 文件列表,如果提供的路径是收藏. 如果一个可写字的Stream被传入,反应体会被流入其中.
    
    ```js
    const { bodyText } = await rc.get('/db/rest-test/test.xml')
    console.log(bodyText)
    ```
    
-   `del(path)`: 从已存在的db 实例中删除资源和收藏
    
    ```js
    await rc.del('/db/rest-test/test.xml')
    ```
    

来看看 [剩余客户实例](https://npmcn.com/package/%40existdb/node-exist/spec/examples/rest.mjs)。 。 。 . REST客户使用 [明白了吗](https://github.com/sindresorhus/got#readme) 图书馆 并用流水和发电机工作. 看这个 [休息测试](https://npmcn.com/package/%40existdb/node-exist/spec/tests/rest.js) 以看到实例.

### XML - RPC 相机

创建、阅读和删除收藏 :

```js
import { getXmlRpcClient } from '@existdb/node-exist'
const db = getXmlRpcClient()

db.collections.create('/db/apps/test')
  .then(result => db.collections.describe('/db/apps/test'))
  .then(result => console.log('collection description:', result))
  .catch(e => console.error('fail', e))
```

将 XML 文件上传到数据库

```js
import { getXmlRpcClient } from '@existdb/node-exist'
const db = getXmlRpcClient()

db.documents.upload(Buffer.from('<root/>'))
  .then(fileHandle => db.documents.parseLocal(fileHandle, '/db/apps/test/file.xml'))
  .then(result => db.documents.read('/db/apps/test/file.xml'))
  .then(result => console.log('test file contents', result))
  .catch(error => console.error('fail', error))
```

由于与数据库的所有交互都是承诺,您也可以使用同源函数

```js
import { getXmlRpcClient } from '@existdb/node-exist'
const db = getXmlRpcClient()

async function uploadAndParse (filePath, contents) {
  const fileHandle = await db.documents.upload(contents)
  await db.documents.parseLocal(fileHandle, filePath, {})
  return filePath
}

try {
  const filePath = await uploadAndParse('/db/apps/test-file.xml', Buffer.from('<root/>'))
  console.log("uploaded", filePath)
} catch (error) {
  console.error(error)
}
```

你也可以看看这个 [实例](https://npmcn.com/package/%40existdb/node-exist/spec/examples) 更多的用例.

## 连接选项

在上一节中,你了解到有两个 API 您可以用来与存在db 实例交互 .

两种客户端构造函数都接受类型选项参数 `NodeExistConnectionOptions`。 。 。 . 毫无论据地召唤他们,如上述例子将使用 默认选项.

```js
{
  basic_auth: {
    user: 'guest',
    pass: 'guest'
  },
  protocol: 'https:',
  host: 'localhost',
  port: '8443',
  path: '/exist/rest'|'/exist/xmlrpc'
}
```

**注:** 这个 `path` 属性,到达 API 的终点, 对 REST 不同(`'/exist/rest'`)和XML-RPC(`'/exist/xmlrpc'`) (中文(简体) ). 你很可能不需要改变它。 不过,如果你需要的话 让你可以控制这些.

### 含有默认值的 REST 客户端

```js
import { getRestClient } from '@existdb/node-exist'
const rest = getRestClient({
  basic_auth: {
    user: 'guest',
    pass: 'guest'
  },
  protocol: 'https:',
  host: 'localhost',
  port: '8443',
  path: '/exist/rest'
})
```

### 默认的 XmlRpc 客户端

```js
import {getXmlRpcClient} from '@existdb/node-exist'
const db = getXmlRpcClient({
  basic_auth: {
    user: 'guest',
    pass: 'guest'
  },
  protocol: 'https:',
  host: 'localhost',
  port: '8443',
  path: '/exist/xmlrpc'
})
```

### 实例

-   联系人不是客人
    
    ```js
    {
      basic_auth: {
        user: 'me',
        pass: '1 troubadour artisanal #compost'
      }
    }
    ```
    
-   连接到 a **地方发展** 使用 HTTP 的服务器
    
    ```js
    {
      protocol: 'http:',
      port: 8080
    }
    ```
    
-   连接到服务器 **无效** 或者说 **过期** 证书.
    
    ```js
    {
      host: 'here.be.dragons',
      rejectUnauthorized: false
    }
    ```
    
    **注:** 对于远程主机来说,此考虑 _不良做法_ 因为它只是 提供虚假的安全感. 对于被认为是本地的主机 - `localhost`, (中文(简体) ), `127.0.0.1` 财务报告和审定财务报表 `[::1]` - 说吧 这是自动设置的, 因为不可能有信任的证书 用于本地主机.
    
-   放弃需要超过十分钟的请求
    
    ```js
    {
      timeout: 600000
    }
    ```
    
    `timeout` 以毫秒计,既适用于等待响应 标题和两块反应体之间的暂停. 默认, `0`,无限期等待,所以运行中的查询不会被剪切 由客户关闭。 查询和REST `post` 接受一个 `timeout` 中标 选项,用于一个单调. 软件包操作`db.app.*`从来没有时间.
    

### 从环境读取选项

`readOptionsFromEnv` 提供了阅读连接选项的舒适方式 从一组环境变量中

| 变量名称 | 默认 | 说明 |
| --- | --- | --- |
| `EXISTDB_USER` | _无_ | 用户用于连接数据库并使用 |
| `EXISTDB_PASS` | _无_ | 在数据库中认证用户的密码 |
| `EXISTDB_SERVER` | `https://localhost:8443` | 要连接到的数据库实例的 URL( 只允许 http 和 https 协议) |
| `EXISTDB_TIMEOUT` | _无_ (无限期等待) | 毫秒前,请求时间结束, `0` 无限期等待 |

**注:** 作为用户以外的一个实例连接 `guest` _两者_ `EXISTDB_USER` _财务报告和审定财务报表_ `EXISTDB_PASS` 必须准备好!

```js
import {getXmlRpcClient, getRestClient, readOptionsFromEnv} from '@existdb/node-exist'
const db = getXmlRpcClient(readOptionsFromEnv())
const rest = getRestClient(readOptionsFromEnv())
```

更多细节,请查看如何使用 [连接脚本](https://npmcn.com/package/%40existdb/node-exist/spec/connection.js) 用于测试和全部测试 [示例脚本](https://npmcn.com/package/%40existdb/node-exist/spec/examples)。 。 。 .

## 构成部分

这个 **XML - RPC 相机** 命令按其运行对象分组为组件. 每个方法都回报一个承诺.

### 查询

状况:工作

`execute`, (中文(简体) ), `read` 财务报告和审定财务报表 `readAll` 接受一个 `timeout` 内 `options`输入 毫秒( 毫秒)`0` (无限制地等待)。 它超越了连接 [超时](https://npmcn.com/package/%40existdb/node-exist/#readme-connection-options) 仅用于此查询,而不发送到 数据库.

```js
db.queries.readAll(query, { variables, timeout: 0 })
```

#### 执行

```js
db.queries.execute(query, options)
```

#### 读取

```js
db.queries.read(query, options)
```

#### 全部读取

此便利函数调用查询 。 计数后检索所有结果页面,并在数组中返回.

```js
db.queries.readAll(query, options)
```

**示例**

```js
const query = `xquery version "3.1";
xmldb:get-child-collections($collection)
  => string-join(",\n")
`
const options = { variables: collection: "/db/apps" }

db.queries.readAll(query, options)
  .then(result => {
    const response = Buffer.concat(result.pages).toString() 
    console.log(response)
  })
  .catch(error => console.error(error))
```

#### 计数

```js
db.queries.count(resultHandle)
```

#### 检索

```js
db.queries.retrieveResult(resultHandle, page)
```

#### 全部检索

```js
db.queries.retrieveAll(resultHandle)
```

#### 释放

服务器上的免费结果

```js
db.queries.releaseResult(resultHandle)
```

### 文档

文档可以被视为文件. 如果它的类型不是二进制的话, 它可能会被索引 .

#### 上传

解析为文件控件,然后可以被 `db.documents.parseLocal`。 。 。 .

```js
db.documents.upload(Buffer.from('test'))
```

#### 解析本地语言

```js
db.documents.parseLocal(fileHandle, 'foo/test.txt')
```

#### 读取

读取存储为 XML 的资源 (S)`XMLResource`) (中文(简体) ). 你可以控制他们 按设置序列化 [序列化选项](https://exist-db.org/exist/apps/doc/xquery.xml?field=all&id=D3.49.19#serialization) 在选项参数中.

使用默认序列化选项 .

```js
db.documents.read('foo.xml')
```

强制 XML 声明要返回 .

```js
db.documents.read('foo.xml', { "omit-xml-declaration": "no" })
```

强制文件以一行空行结尾( 自 eXist- db v 6. 0.

```js
db.documents.read('foo.xml', { "insert-final-newline": "yes" })
```

#### 已读

读取存储为二进制的资源( R)`BinaryResource`内在存在,如" ", 文本文件、PDF、CSS、图像等.

```js
db.documents.readBinary('foo.xml')
```

#### 删除

```js
db.documents.remove('foo.xml')
```

### 资源

状况:工作

在数据库中,资源按其路径确定. 文档 _财务报告和审定财务报表_ 收藏是资源.

#### 说明

```js
db.resources.describe(resourcePath)
```

#### 设置

```js
db.resources.setPermissions(resourcePath, 400)
```

#### 获得许可

```js
db.resources.getPermissions(resourcePath)
```

### 收款

状况:工作

#### 创建

```js
db.collections.create(collectionPath)
```

#### 删除

```js
db.collections.remove(collectionPath)
```

#### 说明

```js
db.collections.describe(collectionPath)
```

#### 读取

```js
db.collections.read(collectionPath)
```

#### 已存在

此函数检查收藏是否存在 .

-   返回时 `true` 如果收藏已存在且当前用户可以打开
-   返回时 `false` 如果收藏不存在
-   如果收藏已存在但当前用户无法执行,则丢弃例外 打开它

```js
db.collections.exists(collectionPath)
```

#### 已存在并可以打开

此函数检查收藏是否存在, 如果确实存在, 如果当前用户可以访问它 .

-   返回时 `true` 如果收藏已存在且当前用户可以打开
-   返回时 `false` 如果收藏不存在
-   如果收藏已存在但当前用户无法执行,则丢弃例外 打开它

```js
db.collections.existsAndCanOpen(collectionPath)
```

### 应用

状况:工作

#### 上传

上传 XAR后可以安装

```js
db.app.upload(xarBuffer, xarName)
```

**示例**

```js
const xarContents = fs.readFileSync('spec/files/test-app.xar')

db.app.upload(xarContents, 'test-app.xar')
  .then(result => console.log(result))
  .catch(error => console.error(error))
```

#### 安装

安装上传的 XAR( 这将调用 `repo:install-and-deploy-from-db`) (中文(简体) ). 为额外安全起见,先前安装的版本将在前被移除 安装新版本 .

依赖性将从 [http://sexual-db.org/sexual/apps/public-repo 互联网档案馆的存檔,存档日期2013-12-22](http://exist-db.org/exist/apps/public-repo) 默认. 如果您想要使用不同的寄存器, 则提供可选 `customPackageRepoUrl`。 。 。 .

```js
db.app.install(xarName[, customPackageRepoUrl])
```

**示例**

```js
db.app.install('test-app.xar')
  .then(result => console.log(result))
  .catch(error => console.error(error))
```

**回返**

```js
{
  "success": true,
  "result": {
    "update": false, // true if a previous version was found
    "target": "/db/apps/test-app"
  }
}
```

**错误**

```js
{
  success: false,
  error: Error
}
```

#### 删除

卸载 _财务报告和审定财务报表_ 删除其命名空间 URL 识别的应用程序. 如果没有应用 `packageUri` 由此可以发现,这是成功的.

```js
db.app.remove(packageUri)
```

**示例**

```js
db.app.remove('http://exist-db.org/apps/test-app')
  .then(result => console.log(result))
  .catch(error => console.error(error))
```

**回返**

```js
{ success: true }
```

**错误**

```js
{
  success: false,
  error: Object | Error
}
```

#### 软件包收集

节点- 存在将上传的收藏路径 软件包改为(`/db/pkgtmp`) (中文(简体) ). 用于清理 相助安设.

**示例**

```js
db.documents.remove(`${db.app.packageCollection}/test-app.xar`)
```

### 指数

状态: 待办

### 用户

状况:工作

#### 获取用户信息

将返回给定用户的信息 .

```js
db.users.getUserInfo(username)
```

示例

```js
db.users.getUserInfo('admin')
```

回返情况:

```js
{
    uid: 1048574,
    'default-group-id': 1048575,
    umask: 18,
    metadata: {
      'http://exist-db.org/security/description': 'System Administrator',
      'http://axschema.org/namePerson': 'admin'
    },
    'default-group-name': 'dba',
    'default-group-realmId': 'exist',
    name: 'admin',
    groups: [ 'dba' ],
    enabled: 'true'
}
```

#### 列表

```js
db.users.list()
```

返回一组用户信息对象(见 [获取用户信息 ()](https://npmcn.com/package/%40existdb/node-exist/#readme-getuserinfo)) (中文(简体) ).

### 服务器

状况:工作

#### 版本

查询运行在服务器上的 eXist-db 版本 . 返回 SemVer 版本为字符串(例如:. `5.4.1` 或者说 `6.1.0-SNAPSHOT`) (中文(简体) ).

```js
db.server.version()
```

#### 同步到磁盘

```js
db.server.syncToDisk()
```

#### 关闭

```js
db.server.shutdown()
```

注:无道再提.

## 命令行脚本

您可以使用此库来构建一个命令行界面,与已存在的b实例相互作用. 几个基本 [实例](https://npmcn.com/package/%40existdb/node-exist/spec/examples) 如何做到这一点将包含在这个寄存器中.

示例

```bash
spec/examples/exist-ls /db/apps
```

**注:** 来看看 [页:1](https://github.com/eXist-db/xst) 对于一个CLI客户端 建立节点-性别.

## 测试

所有测试都在 **光谱/测试** 并写入 [磁带](https://npmjs.org/tape)

```bash
npm test
```

**注:** 您可以覆盖环境变量的连接设置 。 见 [实例](https://npmcn.com/package/%40existdb/node-exist/spec/examples/readme.md) 更多信息.

要使用不同的服务器执行单个运行, 您也可以直接定义变量 :

```bash
EXISTDB_SERVER=http://localhost:8888 npm test
```

## 路线图

-   [x] 切换到使用 eXist-db 的 REST- API( 可通过 [休息客户](https://npmcn.com/package/%40existdb/node-exist/#readme-rest-client)(中文(简体) )
-   [x] 重建ES6模块
-   [x] 更好的类型提示

## 兼容性

**节点性别** 测试与 **eXist-db、4、5和6**。 。 。 . 除XAR安装外,它应该与第3版相兼容.

## 免责声明

**自己冒险使用.**

这个软件是安全的开发. 它可能被用于与生产实例合作,但在你的数据丢失前再三思考.

## 常见问题

### @existdb/node-exist 是什么？

与 eXist DB 的 XML- RPC API 基于承诺的交互

### 如何安装 @existdb/node-exist？

在项目目录运行 npm install @existdb/node-exist，或使用 pnpm add / yarn add / bun add。

### @existdb/node-exist 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/existdb\_\_node-exist 是否存在。

### @existdb/node-exist 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @existdb/node-exist 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @existdb/node-exist 可以商用吗？

@existdb/node-exist 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @existdb/node-exist 的下载量有多少？

根据 npm 官方下载统计，@existdb/node-exist 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,000 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @existdb/node-exist 还在维护吗？

最新版本 8\.0\.0 发布于 2026/09/13（2 个月前）；至今共发布 48 个版本，其中过去 12 个月发布了 3 个；首次发布于 2018/07/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。