將 DOCX 檔案轉換為 Markdown 是開發人員常見的需求，因為他們需要輕量且適合版本控制的文件。 Aspose.HTML Cloud SDK for PHP 讓您只需幾個 API 呼叫，即可在 PHP 中執行此 DOCX 轉換為 MD 的操作。本指南將逐步說明必要的設定、展示完整的程式碼範例，並說明如何微調輸出以獲得乾淨的 Markdown。您還將看到如何使用 cURL 透過 REST 呼叫相同的轉換，以支援雲端原生情境。

步驟：在 PHP 中將 DOCX 轉換為 MD

  1. 取得存取權杖 - 使用您的 Aspose Cloud 用戶端 ID 與密鑰，透過 OAuth 端點請求暫時的存取權杖。
  2. 上傳來源 DOCX - 可使用 UploadFile 方法將檔案上傳至 Aspose 儲存，或提供可公開存取的 URL。
  3. 建立轉換請求 - 建立 ConvertDocumentRequest 物件，將 format 設為 md，並可選擇性指定轉換選項。
  4. 執行轉換 - 呼叫 HtmlApi 類別的 ConvertDocument 方法（API 參考）。
  5. 下載 Markdown - 從回應串流中取得產生的 .md 檔案，將其儲存至本機或進一步處理。

PHP 中的 DOCX 轉 MD 轉換腳本 - 完整程式碼範例

以下腳本展示了使用 Aspose.HTML Cloud SDK for PHP 進行完整端到端轉換的示例。

<?php
require 'vendor/autoload.php';

use Aspose\HTML\Cloud\Sdk\Api\HtmlApi;
use Aspose\HTML\Cloud\Sdk\Configuration;
use Aspose\HTML\Cloud\Sdk\Model\ConvertDocumentRequest;

// ---------------------------------------------------------------------
// 1. Configure SDK with your client credentials
// ---------------------------------------------------------------------
$config = new Configuration();
$config->setClientId('YOUR_CLIENT_ID');
$config->setClientSecret('YOUR_CLIENT_SECRET');

// ---------------------------------------------------------------------
// 2. Initialize HtmlApi
// ---------------------------------------------------------------------
$htmlApi = new HtmlApi($config);

// ---------------------------------------------------------------------
// 3. Prepare conversion request
// ---------------------------------------------------------------------
$inputFile = 'sample.docx';          // Path to your DOCX file
$outputFormat = 'md';                // Target format
$request = new ConvertDocumentRequest($inputFile, $outputFormat);

// ---------------------------------------------------------------------
// 4. Perform conversion
// ---------------------------------------------------------------------
try {
    $response = $htmlApi->convertDocument($request);
    $markdown = $response->getBody()->getContents();

// -----------------------------------------------------------------
    // 5. Save the Markdown output
    // -----------------------------------------------------------------
    file_put_contents('output.md', $markdown);
    echo "Conversion successful. Markdown saved to output.md\n";
} catch (Exception $e) {
    echo "Error during conversion: " . $e->getMessage() . "\n";
}
?>

注意： 此程式碼範例示範了核心功能。在將其用於您的專案之前，請確保更新檔案路徑（sample.docx、output.md），驗證所有必要的相依項目已正確安裝，並在開發環境中徹底測試。如遇到任何問題，請參閱官方文件或聯繫支援團隊以獲得協助。

基於雲端的 DOCX 轉 Markdown 轉換（使用 REST API 及 cURL）

您可以在不使用 SDK 的情況下，直接呼叫 Aspose.HTML Cloud REST 端點來實現相同的結果。

  1. 驗證並取得存取權杖
curl -X POST "https://api.aspose.cloud/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. 上傳來源檔案（如果未使用公開 URL）
curl -X PUT "https://api.aspose.cloud/v4.0/html/storage/file/sample.docx" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
        --data-binary "@sample.docx"
  1. 執行轉換
curl -X POST "https://api.aspose.cloud/v4.0/html/convert/md" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"inputPath":"sample.docx","outputPath":"output.md"}'
  1. 下載 Markdown 輸出
curl -X GET "https://api.aspose.cloud/v4.0/html/storage/file/output.md" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -o output.md

如需了解請求參數的更多詳細資訊，請參閱官方 API 文件。

在 PHP 中的安裝與設定

  1. 透過 Composer 安裝 SDK 
    composer require aspose-html-cloud
  2. 下載最新發行版 如果您偏好手動安裝：下載套件。
  3. 設定您的認證 - 在 Configuration 物件中設定 client_id 和 client_secret（請參考程式碼範例）。
  4. 驗證安裝，執行簡單的 php -r "echo phpinfo();" 腳本以確保自動載入器正常運作。
  5. 套用臨時授權 以進行測試：前往 臨時授權頁面 並依照說明操作。

在 PHP 中使用 Aspose.HTML 進行 DOCX 轉 MD 轉換

Aspose.HTML 提供一個基於雲端的轉換引擎，能夠完整理解 DOCX 規範，包括複雜的版面配置、表格和嵌入的圖像。將文件發送至服務後，您可以將處理工作卸載到可擴展的後端，從而消除對笨重本地庫的需求。

Aspose.HTML 功能

  • High‑Fidelity Rendering - 在轉換為 Markdown 時保留樣式、表格和圖像。
  • Multiple Output Formats - 支援 HTML、PDF、PNG、JPEG，以及 Markdown (MD)。
  • Cloud‑Native Architecture - 自動擴展，並可透過 HTTPS 在防火牆後運行。
  • Extensive API - 透過 REST 和 SDK 提供對轉換選項的細緻控制。

配置轉換選項以獲得最佳 Markdown 輸出

ConvertDocumentRequest 允許您微調 Markdown 結果：

選項 說明
preserveTableStructure 保持表格的行與列完整（預設：true）。
includeImages 將圖像嵌入為 base64 字串，或保持為外部檔案。
headingLevelOffset 調整標題層級以符合您的文件層次結構。
removeStyles 移除內嵌的 CSS ，以獲得更乾淨的純文字輸出。

在呼叫 convertDocument 之前，透過請求模型設定這些選項。

優化轉換效能

  • 批次處理多個檔案 - 上傳多個 DOCX 檔案，並在單一 API 呼叫中進行轉換，以減少往返延遲。
  • 重複使用存取權杖 - 權杖有效期為一小時；將其快取，而不是為每個檔案請求新的權杖。
  • 壓縮輸入檔案 - 較小的負載可加快上傳與處理速度。
  • 平行請求 - 對於大量工作負載，發送同時的轉換請求，並遵守服務速率限制。

DOCX 轉 MD 的最佳實踐

  • 驗證輸入 - 確保 DOCX 檔案在上傳前未損壞。
  • 清理 Markdown - 轉換後，執行 linter 以修復任何格式異常。
  • 安全儲存結果 - 將產生的 .md 檔案保存於受版本控制的儲存庫中。
  • 監控 API 使用情況 - 透過 Aspose Cloud 儀表板追蹤請求次數與回應時間，以避免被限制。

結論

透過使用 Aspose.HTML Cloud SDK for PHP，您可以在最少的程式碼下可靠地將 DOCX 檔案轉換為 Markdown。此 SDK 能處理複雜的版面配置，保留關鍵格式，並提供可設定的選項以產生乾淨的 MD 輸出。 在正式上線時，請從 Aspose 商店購買完整授權；亦可透過臨時授權頁面取得評估用的臨時授權。將提供的程式碼範例整合至您的工作流程，即可在 PHP 應用程式中輕鬆實現無縫的文件轉換。

常見問題

如何在轉換過程中處理大型 DOCX 檔案？
先將檔案上傳至 Aspose storage，然後觸發轉換。雲端服務能有效處理大型檔案，您可以透過 API 監控進度。

我可以在一次請求中將多個 DOCX 檔案轉換為 Markdown 嗎？
可以。使用批次轉換端點，或在 SDK 中迭代檔案，重複使用相同的存取權杖以提升效能。

如果我需要將圖像內嵌而不是作為外部文件呢？
將 includeImages 選項設置為 true，並選擇 embedImages 模式。SDK 將把圖像作為 base64 字串直接嵌入 Markdown 中。

SDK 是否相容於 PHP 8.x？
Aspose.HTML Cloud SDK for PHP 支援 PHP 7.4 及更新版本，包括 PHP 8.x。請確保已啟用所需的擴充功能 (cURL、JSON)。

閱讀更多