---
title: "安装"
description: "设置凭据并安装转换扩展，用于导入和导出文档。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/getting-started/install"
---

# 安装

设置凭据并安装转换扩展，用于导入和导出文档。

为你的项目设置凭据并安装转换扩展。

## 前置条件

1. 开始 [免费试用或选择订阅](https://cloud.tiptap.dev/v2/billing)。
2. 设置对 [Tiptap 私有 npm 仓库](https://tiptap.zhcndoc.com/guides/pro-extensions.md) 的访问权限。

## 身份验证

Most conversion extensions and REST API endpoints require a signed JWT. The DOCX export extension is the exception and works without credentials.

Set the `aud` claim to `"Convert"` and grant the format and direction actions the integration uses. To create a key pair and sign a token, see [Authentication](https://tiptap.zhcndoc.com/authentication.md).

### Actions

Each conversion direction has its own action, so a token scoped to exactly the operations a feature needs never silently widens when a new direction is added:

| Action                    | Grants                    |
| ------------------------- | ------------------------- |
| `Convert:Import:Docx`     | 导入 DOCX                   |
| `Convert:Export:Docx`     | 导出 DOCX                   |
| `Convert:Import:Markdown` | 导入 Markdown               |
| `Convert:Export:Markdown` | 导出 Markdown               |
| `Convert:Export:Doc`      | 导出旧版 DOC                  |
| `Convert:Export:Odt`      | 导出 ODT                    |
| `Convert:Export:Epub`     | 导出 EPUB                   |
| `Convert:Export:Pdf`      | 导出 PDF                    |
| `Convert:Fonts`           | 管理字体缓存（`/fonts/*`），仅限本地部署 |

不带明确格式的旧路由（`POST /v2/import`、`POST /v2/export`）分别检查 `Convert:Import:Docx` 和 `Convert:Export:Docx`。

### Example token

```json
{
  "iss": "env_abc123",
  "aud": "Convert",
  "exp": 1777033105,
  "permissions": [
    { "action": "Convert:Import:Docx", "resource": "*" },
    { "action": "Convert:Export:Docx", "resource": "*" },
    { "action": "Convert:Export:Pdf", "resource": "*" }
  ]
}
```

使用此令牌请求 `POST /v2/export/pdf` 会成功。`POST /v2/export/odt` 会返回 `permission_denied` 错误，指出缺少的操作权限。

Send the token in the `Authorization: Bearer <jwt>` header for REST calls, or pass it through the `token` option on the editor extensions. You do not send an App ID.

> **Importing comments:**
>
> 导入包含批注的文档时，会将这些批注写入 Document Server。请将 `Documents:Write` 与你的 `Convert:Import:*` 操作一并包含，这样导入才能保存这些批注。参见 [cross-service actions](https://tiptap.zhcndoc.com/authentication.md#cross-service-actions)。

### Error responses

当令牌缺少所需权限时，服务会返回 `403 Forbidden`，内容如下：

```json
{
  "message": "Token is missing permission Convert:Export:Pdf.",
  "code": "permission_denied"
}
```

如果环境的订阅根本不包含 Convert，则响应为 `403`，且 `code: feature_not_available`。上游云错误会被清晰映射：`429 rate_limited`、`503 service_unavailable`，以及 `401 token_expired` / `signature_invalid`，这样你的客户端就能区分无效令牌和临时性的云端问题。

> **Maintaining an existing integration?:**
>
> 之前的 App ID 和 secret 流程记录在 [Legacy authentication](https://tiptap.zhcndoc.com/authentication/legacy.md) 中，并且仍然可用。

## 安装包

安装你需要支持的格式所对应的扩展。

**导入：**

```bash
# DOCX 导入（编辑器扩展）
npm install @tiptap-pro/extension-import-docx
```

**导出：**

```bash
# DOCX 导出（编辑器扩展，无需身份验证）
npm install @tiptap-pro/extension-export-docx

# PDF 导出
npm install @tiptap-pro/extension-export-pdf

# ODT 导出
npm install @tiptap-pro/extension-export-odt

# EPUB 导出
npm install @tiptap-pro/extension-export-epub

# Markdown 导出
npm install @tiptap-pro/extension-export-markdown
```

> **DOCX 导出不需要身份验证:**
>
> `@tiptap-pro/extension-export-docx` 包完全在客户端处理转换。无需 JWT、
> App ID 或服务器调用。

## Next Step

Select your format in the sidebar to view the complete setup and configuration guide for each extension and REST API.