在 Node.JS 中将 PDF 转换为 DOCX

Mon, 03 Aug 2026 10:51:03 +0000

将 PDF 文件转换为 DOCX 格式是构建文档中心应用时的常见需求，尤其是当您需要可编辑的 Word 输出时。 GroupDocs.Conversion Cloud SDK for Node.js 提供了强大的 API，使此任务变得简单且可扩展。在本指南中，您将看到完整的异步代码示例，了解如何使用 cURL REST 调用实现相同的结果，设置 SDK，并应用最佳实践建议以实现可靠的转换。

完整代码示例：在 Node.JS 中进行异步 PDF 转 DOCX 转换

本示例演示如何使用 GroupDocs.Conversion Cloud SDK for Node.js 执行异步的 PDF 转 DOCX 转换。

// PDF to DOCX conversion using GroupDocs.Conversion Cloud SDK for Node.js

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const path = require('path');

// -------------------- Configuration --------------------
const CLIENT_ID = process.env.GROUPDOCS_CLIENT_ID || 'YOUR_CLIENT_ID';
const CLIENT_SECRET = process.env.GROUPDOCS_CLIENT_SECRET || 'YOUR_CLIENT_SECRET';

// Initialize API client
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
apiInstance.apiClient = new GroupDocsConversionCloud.ApiClient();
apiInstance.apiClient.basePath = 'https://api.groupdocs.cloud';
apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;

// -------------------- Conversion Logic --------------------
async function convertPdfToDocx() {
    try {
        // Input file information (must already be uploaded to GroupDocs Cloud storage)
        const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
        inputFileInfo.filePath = path.normalize('input.pdf'); // generic path in cloud storage

// DOCX specific conversion options (optional, shown for demonstration)
        const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
        docxOptions.preserveOriginalFormatting = true; // keep original PDF layout as much as possible
        docxOptions.password = null; // if PDF is password protected, set it here

// Build conversion request
        const convertRequest = new GroupDocsConversionCloud.ConvertDocumentRequest();
        convertRequest.format = 'docx';
        convertRequest.fileInfo = inputFileInfo;
        convertRequest.outputPath = path.normalize('output.docx'); // result will be stored in cloud storage
        convertRequest.options = docxOptions; // attach format‑specific options

// Perform conversion (async)
        const conversionResult = await apiInstance.convertDocument(convertRequest);

// conversionResult contains the path of the generated file and other metadata
        console.log('Conversion succeeded.');
        console.log('Output file path:', conversionResult.path);
        console.log('File size (bytes):', conversionResult.size);
    } catch (error) {
        // Detailed error handling
        if (error.response && error.response.body) {
            console.error('API error:', error.response.body);
        } else {
            console.error('Unexpected error:', error.message);
        }
    }
}

// -------------------- Execution --------------------
(async () => {
    // Optional: set a timeout to avoid hanging indefinitely
    const timeoutMs = 300000; // 5 minutes
    const timeout = setTimeout(() => {
        console.error('Conversion timed out after', timeoutMs / 1000, 'seconds');
        process.exit(1);
    }, timeoutMs);

await convertPdfToDocx();

clearTimeout(timeout);
    // Graceful shutdown
    process.exit(0);
})();

注意： 此代码示例演示了核心功能。在项目中使用之前，请确保更新文件路径（input.pdf、output.docx 等）以匹配实际位置，验证已安装所有必需的依赖项，并在开发环境中彻底测试。如果遇到任何问题，请参阅官方文档或联系支持团队获取帮助。

使用 cURL 和 REST API 转换文档

您可以通过直接调用 GroupDocs.Conversion Cloud REST 端点，在无需编写代码的情况下实现相同的 PDF 转 DOCX 转换。以下步骤展示了如何获取访问令牌、上传 PDF、启动转换以及下载生成的 DOCX 文件。

进行身份验证并获取访问令牌
将 YOUR_CLIENT_ID 和 YOUR_CLIENT_SECRET 替换为您的凭据。

curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type":"client_credentials",
           "client_id":"YOUR_CLIENT_ID",
           "client_secret":"YOUR_CLIENT_SECRET"
         }'

响应中包含 access_token，您将在后续调用中使用它。

上传源 PDF

curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file/input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/pdf" \
     --data-binary @./local/input.pdf

执行转换

curl -X POST "https://api.groupdocs.cloud/v1.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "format":"docx",
           "fileInfo":{"filePath":"input.pdf"},
           "outputPath":"output.docx",
           "options":{"preserveOriginalFormatting":true}
         }'

响应返回生成的 DOCX 文件的路径。

下载已转换的 DOCX

curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file/output.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o ./local/output.docx

有关请求负载和其他选项的更多详细信息，请参阅官方 API 文档。

拆解 Node.JS 中的 PDF 转 DOCX 转换

以下是异步代码示例关键部分的简要概述。

导入并配置客户端

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();

ConversionApi 类（API 参考）是所有转换操作的入口点。

设置身份验证凭据

apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;

JWT 身份验证可确保对云服务的每个请求的安全。

准备输入文件信息

const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
inputFileInfo.filePath = path.normalize('input.pdf');

FileInfo 告诉 API 源 PDF 在 GroupDocs Cloud 存储中的位置。

配置 DOCX‑特定选项

const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
docxOptions.preserveOriginalFormatting = true;

DocxConvertOptions 让您保持原始布局，并在需要时处理密码。

创建并发送转换请求

const convertRequest = new GroupDocsConversionCloud.ConvertDocumentRequest();
convertRequest.format = 'docx';
convertRequest.fileInfo = inputFileInfo;
convertRequest.outputPath = path.normalize('output.docx');
convertRequest.options = docxOptions;
const conversionResult = await apiInstance.convertDocument(convertRequest);

convertDocument 方法执行实际的转换，并返回元数据，例如输出路径和文件大小。

安装和配置 GroupDocs.Conversion Cloud SDK for Node.JS

安装软件包

npm install groupdocs-conversion-cloud

该软件包可从公共 npm 注册表获取。有关版本详细信息，请参阅下载页面。

先决条件
- Node.js 12 或更高版本。
- 具有 client ID 和 client secret 的 GroupDocs Cloud 帐户。
在项目中初始化 SDK（摘自完整示例）

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
apiInstance.apiClient.basePath = 'https://api.groupdocs.cloud';

如果使用区域端点，请调整 basePath。

高性能文档转换的最佳实践

重用 API 客户端 而不是为每次转换创建新实例；这可以减少身份验证开销。
启用流式上传 以处理大型 PDF，避免将整个文件加载到内存中。
设置合理的超时时间（例如 5 分钟），以防止作业挂起，同时仍允许复杂文档完成。
仅在需要时保留原始格式；禁用它可以加快仅文本 PDF 的转换速度。
监控 API 使用限制 在您的 GroupDocs 帐户仪表板中，以避免批量操作期间被限流。

结论

GroupDocs.Conversion Cloud SDK for Node.js 使 PDF 转换为 DOCX 变得直观，无论您是更喜欢功能齐全的库还是使用 cURL 的直接 REST 调用。通过遵循异步代码示例、正确配置客户端并应用上述性能技巧，您可以在任何 Node.JS 服务中集成可靠的文档转换。请记得为生产环境获取适当的许可证；定价详情可在产品页面查看，临时许可证可从临时许可证页面获取以进行评估。

常见问题

Node.JS 中的 PDF 转 DOCX 转换如何处理复杂布局？
SDK 默认尝试保留原始格式。您可以在 DocxConvertOptions 中切换 preserveOriginalFormatting 以在保真度和速度之间进行权衡。查看 API 参考了解所有选项。
PDF 转 DOCX 转换的文件大小限制是什么？
云服务对免费账户接受的文件大小上限为 200 MB；更大的文件需要升级计划。上传采用流式传输，因此服务器的内存使用保持低。
我可以在单个请求中将多个 PDF 转换为 DOCX 吗？
API 每次请求只处理一个文档，但您可以在 Node.JS 中遍历文件列表并并行运行转换，遵守您账户的并发限制。
是否有办法在没有付费许可证的情况下本地测试转换？
是的，您可以从临时许可证页面请求临时评估许可证。这为开发和测试提供完整功能。

nodejs conversion on Document Processing REST APIs | GroupDocs Cloud