1. 項目緣起與核心痛點最近在整理團隊資料時遇到了一個非常具體且磨人的需求需要把金山文檔里一個包含了幾百個文件的協作空間全部下載到本地進行歸檔和備份。這個需求聽起來簡單但實際操作起來你會發現金山文檔官方并沒有提供一個“一鍵打包下載”的功能。你只能一個個文件點開再手動選擇“下載為”某種格式效率低到令人發指而且極其容易出錯或遺漏。這讓我想起了以前處理類似辦公文檔批量操作時的經歷比如處理Excel表格或者Word文檔但金山文檔作為一個在線協作平臺它的文件存儲和訪問邏輯又有些不同。這個“坑”的本質在于金山文檔的在線文件系統是動態加載的其文件列表和下載鏈接并非靜態呈現而是通過JavaScript動態渲染和接口調用來完成的。這就意味著傳統的、簡單的HTTP請求抓取頁面HTML的方式行不通。你需要模擬瀏覽器的行為或者直接與它的后端API進行“對話”。我的目標很明確寫一個腳本能自動登錄或使用已有登錄態、遍歷指定文件夾下的所有文件、識別文件類型文檔、表格、幻燈片等、并批量下載到本地且最好能保持原有的文件名和目錄結構。經過一番摸索和嘗試我最終組合使用了Python和瀏覽器開發者工具中的JavaScript形成了一套相對穩定且可復現的解決方案。Python負責整體的流程控制、網絡請求和文件操作而JS代碼主要通過復制粘貼到瀏覽器控制臺執行則用于在已登錄的頁面上下文中快速獲取那些受保護的API令牌和文件列表信息。下面我就把這套方法的核心思路、踩過的坑以及完整的操作步驟記錄下來。2. 技術方案選型與思路拆解面對金山文檔這種復雜的單頁應用SPA直接上手寫Python爬蟲往往會碰壁。我們需要先理解它的數據流。2.1 為什么是Python JS的組合純Python方案如requestsBeautifulSoup在遇到大量JS渲染和反爬機制時會變得非常笨重。你需要處理Cookie、Token、動態參數甚至可能模擬整個登錄流程和頁面交互復雜度極高。純瀏覽器自動化方案如Selenium或Playwright可以完美模擬用戶操作但缺點也很明顯速度慢、資源占用高、不夠穩定且難以進行精細化的錯誤處理和流程控制。因此我采用的是一種“混合動力”方案JS探路利用瀏覽器開發者工具F12在已經手動登錄的金山文檔頁面中執行一些簡短的JS代碼片段。這些代碼運行在頁面的真實上下文中可以輕松訪問到頁面內嵌的API令牌、用戶信息以及通過XHR/Fetch加載的原始JSON數據。這一步的目的是“偵察”獲取那些對Python腳本至關重要的密鑰如access_token和數據結構。Python主攻拿到JS偵察兵獲取的關鍵信息后用Python編寫主腳本。Python腳本使用requests庫攜帶這些令牌直接調用金山文檔的后端API接口進行文件列表的獲取和文件下載。這樣既繞開了復雜的頁面渲染又保證了效率和穩定性。這個組合的核心優勢在于JS用于在“信任環境”已登錄的瀏覽器中安全地獲取憑證Python利用這些憑證進行高效、批量的自動化操作。兩者分工明確各取所長。2.2 核心流程設計整個批量下載流程可以分解為以下幾個關鍵環節我畫了一個簡單的思維導圖來幫助理解開始 │ ├─ 環節1人工介入瀏覽器登錄金山文檔 │ (獲取登錄態Cookie) │ ├─ 環節2JS偵察獲取關鍵令牌(access_token)和空間/文件夾ID │ (在瀏覽器控制臺執行代碼) │ ├─ 環節3Python主腳本啟動 │ │ │ ├─ 3.1 配置階段讀取JS環節獲取的令牌和目標ID │ │ │ ├─ 3.2 遍歷階段調用API遞歸獲取文件列表樹 │ │ │ ├─ 3.3 下載階段根據文件類型構造下載鏈接并保存 │ │ │ └─ 3.4 歸檔階段在本地創建對應文件夾結構 │ └─ 結束本地獲得完整文件備份注意此方案的前提是你擁有目標文檔空間的訪問權限。它解決的是“有權限但操作繁瑣”的問題而非繞過權限驗證。3. 實操第一步環境準備與信息偵察在寫任何代碼之前我們需要準備好“戰場”和“情報”。3.1 Python環境與依賴庫確保你的電腦上安裝了Python 3.6及以上版本。我們主要會用到兩個庫requests用于發送HTTP請求。json用于處理API返回的JSON數據。通常json是Python標準庫無需安裝。只需要安裝requests即可。打開你的終端或命令提示符執行pip install requests如果你需要處理更復雜的網絡情況可以考慮安裝requests_toolbelt但本項目基礎功能不需要。3.2 瀏覽器端的關鍵信息獲取JS偵察這是整個流程中最關鍵的一步我們需要從已登錄的瀏覽器頁面中“提取”出access_token和space_id或folder_id。登錄并打開目標空間用你的瀏覽器Chrome/Firefox/Edge均可正常登錄金山文檔并進入你想要批量下載的那個“協作空間”或“文件夾”的頁面。打開開發者工具按F12打開開發者工具切換到“網絡”(Network)選項卡。為了清晰可以先點擊垃圾桶圖標清空之前的記錄。觸發一次文件列表加載在頁面左側的文件列表區域嘗試滾動或點擊進入某個子文件夾讓瀏覽器發起網絡請求。尋找關鍵請求在“網絡”選項卡中你會看到很多請求。尋找一個類型為fetch或xhr名稱看起來像list或children的請求其URL可能包含https://www.kdocs.cn/api/v3/這樣的路徑。點擊這個請求查看它的“標頭”(Headers)和“響應”(Response)。提取access_token在“標頭”部分找到“請求標頭”下的Authorization字段。它的值通常是Bearer eyJ...這樣一長串字符。eyJ開頭的部分就是你的access_token。復制它。重要這個token具有你的賬戶權限請像保管密碼一樣妥善保管不要泄露。提取空間或文件夾ID方法A從URL獲取。觀察瀏覽器地址欄當你進入一個協作空間時URL可能形如https://www.kdocs.cn/space/SPACE_ID。當你進入一個文件夾時URL可能形如https://www.kdocs.cn/folder/FOLDER_ID。復制這個ID。方法B從API響應獲取。在上一步找到的list請求的“響應”(Response)標簽頁里通常是JSON格式。你可以找到一個id或obj_id字段這就是當前列表的ID。如果是根目錄這個ID可能就是space_id。使用JS代碼快速提取推薦 為了更準確和方便我們可以直接在“控制臺”(Console)標簽頁執行一段JS代碼來獲取這些信息。在Console中輸入以下代碼并回車// 嘗試從localStorage或頁面全局變量中查找token let token localStorage.getItem(access_token) || window.__NUXT__?.state?.user?.token; // 如果上述方法不行從第一個找到的API請求頭里提取需要先觸發過請求 if (!token performance.getEntriesByType(resource).length 0) { // 這是一個簡化的示例實際可能需要更復雜的查找邏輯 console.log(請先觸發一次文件列表加載如滾動然后重試。或手動從Network標簽頁的請求頭中復制Authorization字段值。); } else { console.log(可能的access_token (Bearer部分):, token); } // 獲取當前空間或文件夾ID let path window.location.pathname; let id path.split(/).pop(); // 提取路徑最后一部分 console.log(當前頁面ID:, id); console.log(完整URL:, window.location.href);執行后控制臺會輸出相關信息。請將獲取到的access_token和ID記錄下來后面Python腳本會用到。實操心得有時候access_token可能存儲在sessionStorage或其他加密變量里。如果上述JS代碼沒找到最可靠的方法還是從“網絡”選項卡里找一個成功的API請求直接復制它的Authorization請求頭值。這是萬無一失的方法。4. Python核心腳本編寫與詳解拿到access_token和目標ID后我們就可以開始編寫Python主腳本了。我將腳本分為幾個功能模塊便于理解和修改。4.1 腳本基礎結構與配置首先創建一個Python文件比如kdocs_batch_downloader.py。開頭部分我們引入庫并設置基礎配置。import requests import json import os from urllib.parse import unquote import time # 配置區域 # 在這里填入你在瀏覽器中獲取的信息 ACCESS_TOKEN Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1... # 替換成你的token TARGET_ID 1234567890abcdefg # 替換成你的空間ID或文件夾ID BASE_URL https://www.kdocs.cn/api/v3 # 金山文檔API基礎地址 # 請求頭攜帶認證令牌 HEADERS { Authorization: ACCESS_TOKEN, Content-Type: application/json, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 } # 本地保存的根目錄 SAVE_ROOT ./金山文檔備份 # 配置結束 # 創建保存目錄 os.makedirs(SAVE_ROOT, exist_okTrue) def make_request(url, methodGET, paramsNone, dataNone): 封裝請求函數添加重試和錯誤處理 try: if method.upper() GET: resp requests.get(url, headersHEADERS, paramsparams, timeout30) else: resp requests.post(url, headersHEADERS, jsondata, timeout30) resp.raise_for_status() # 如果狀態碼不是200拋出HTTPError異常 return resp.json() except requests.exceptions.RequestException as e: print(f請求失敗: {url}, 錯誤: {e}) return None代碼解讀ACCESS_TOKEN和TARGET_ID是核心必須替換為你自己獲取的值。User-Agent模擬瀏覽器避免被簡單的反爬機制攔截。make_request函數是對requests的簡單封裝加入了超時和基礎錯誤處理讓后續代碼更簡潔。4.2 遞歸獲取文件列表樹金山文檔的文件夾結構是樹形的。我們需要一個函數來遞歸地獲取某個文件夾或空間根目錄下的所有文件和子文件夾。def get_file_list(node_id, node_typefolder, path): 遞歸獲取文件列表 :param node_id: 當前節點ID空間ID或文件夾ID :param node_type: 節點類型space 或 folder :param path: 當前的本地相對路徑用于構建目錄結構 :return: 返回一個包含所有文件信息的列表 all_files [] current_path os.path.join(path, str(node_id)) # 臨時用ID作為路徑名后續會用真實名稱替換 # 構建API請求參數 if node_type space: url f{BASE_URL}/spaces/{node_id}/children else: # folder url f{BASE_URL}/folders/{node_id}/children params { limit: 100, # 每頁數量最大可能100 order_by: name, asc: 1 } page 1 while True: params[page] page print(f正在獲取 {current_path} 的第 {page} 頁...) data make_request(url, paramsparams) if not data or data not in data: print(f獲取 {node_id} 列表失敗或數據為空。) break items data.get(data, []) if not items: break # 沒有更多數據了 for item in items: item_type item.get(obj_type) # file, folder item_name item.get(name, 未命名).strip() item_id item.get(obj_id) if not item_name or not item_id: continue # 構建文件/文件夾的完整信息字典 item_info { id: item_id, name: item_name, type: item_type, local_path: os.path.join(path, item_name) # 本地保存路徑 } # 如果是文件夾遞歸獲取其內容 if item_type folder: print(f進入文件夾: {item_name}) sub_files get_file_list(item_id, folder, os.path.join(path, item_name)) all_files.extend(sub_files) # 文件夾本身也需要記錄嗎通常我們只記錄文件文件夾在下載時創建即可。 # 這里可以選擇將文件夾信息也加入列表或者不加入。我們不加入只通過local_path創建目錄。 elif item_type file: # 補充文件詳情如下載格式、大小等如果需要 item_info.update({ file_type: item.get(file_type), # doc, sheet, slide等 size: item.get(size), modified_time: item.get(modified_time) }) all_files.append(item_info) print(f找到文件: {item_name}) # 判斷是否還有下一頁這里根據實際API響應調整有些用has_more字段 # 假設 items 數量小于 limit 就是最后一頁 if len(items) params[limit]: break page 1 time.sleep(0.5) # 禮貌性延遲避免請求過快 return all_files關鍵點解析遞歸邏輯函數發現一個folder類型的項目時會遞歸調用自身并將當前路徑path加上文件夾名作為新的路徑傳遞下去。分頁處理API通常會對列表進行分頁。我們使用page和limit參數循環請求直到獲取所有數據。limit100是常見的最大值。路徑處理我們為每個文件計算了一個local_path這個路徑是相對于本地根目錄SAVE_ROOT的。這樣在下載時就能直接創建對應的目錄結構。延遲time.sleep在循環中增加短暫延遲是良好的網絡公民行為可以避免對服務器造成過大壓力也能減少被風控的風險。4.3 文件下載鏈接構造與保存獲取文件列表后下一步是根據文件類型文檔、表格、幻燈片構造正確的下載鏈接并保存到本地。def download_file(file_info, base_save_dir): 下載單個文件 :param file_info: 文件信息字典 :param base_save_dir: 本地保存的根目錄 file_id file_info[id] file_name file_info[name] file_local_path file_info[local_path] file_type file_info.get(file_type, doc) # 默認為文檔 # 1. 創建本地目錄 local_dir os.path.join(base_save_dir, os.path.dirname(file_local_path)) os.makedirs(local_dir, exist_okTrue) # 2. 根據文件類型決定下載格式和API端點 # 金山文檔支持多種導出格式這里我們選擇最通用的格式 download_format_map { doc: (docx, documents), # 文檔 - .docx sheet: (xlsx, spreadsheets), # 表格 - .xlsx slide: (pptx, presentations), # 幻燈片 - .pptx # 可以根據需要添加其他類型如 pdf 等 } if file_type not in download_format_map: print(f暫不支持的文件類型: {file_type}, 文件: {file_name}) return False file_ext, api_type download_format_map[file_type] # 清理文件名中的非法字符并添加后綴 safe_file_name .join([c for c in file_name if c not in r\/:*?|]).strip() local_file_path os.path.join(local_dir, f{safe_file_name}.{file_ext}) # 3. 構造下載鏈接并請求 # 注意下載鏈接可能需要額外的API調用獲取臨時下載地址 download_url f{BASE_URL}/{api_type}/{file_id}/export payload { format: file_ext.upper(), # 如 DOCX, XLSX csrf_token: 需要從頁面獲取或某些接口不需要 # 這是一個潛在的坑 } # 重要直接使用 /export 端點可能不行。更常見的是先獲取文件下載信息。 # 讓我們換一種更可靠的方式模擬“下載為”動作的API。 # 經過分析實際下載往往需要先請求一個/download接口獲取臨時鏈接。 download_info_url f{BASE_URL}/files/{file_id}/download download_info make_request(download_info_url) if not download_info or data not in download_info: print(f獲取文件 {file_name} 下載信息失敗。) # 備選方案嘗試使用預覽鏈接轉換這里需要根據實際API調整。 # 例如有些文件可以通過 /files/{id}/preview 鏈接修改參數獲得下載流。 return False # 假設返回的data里有 download_url 字段 real_download_url download_info[data].get(download_url) if not real_download_url: print(f文件 {file_name} 的下載鏈接為空。) return False # 4. 下載文件流 print(f正在下載: {file_name} - {local_file_path}) try: # 注意下載文件的請求可能不需要Authorization頭或者需要不同的頭。 # 但通常這個download_url是臨時的、帶簽名的可以直接用。 resp requests.get(real_download_url, streamTrue, timeout60) resp.raise_for_status() with open(local_file_path, wb) as f: for chunk in resp.iter_content(chunk_size8192): if chunk: f.write(chunk) print(f下載成功: {local_file_path}) return True except Exception as e: print(f下載文件 {file_name} 時出錯: {e}) # 如果下載失敗可以記錄到日志文件稍后重試 return False避坑指南文件名清洗Windows和Mac/Linux系統對文件名中的特殊字符如\/:*?|處理方式不同直接使用可能報錯。所以需要清洗。下載鏈接的獲取/export端點可能不是通用的。我在這里遇到了第一個大坑。通過分析瀏覽器點擊“下載為”時的網絡請求我發現更常見的流程是先調用一個/files/{id}/download接口該接口返回一個包含臨時download_url的JSON響應這個URL才是真正的文件下載地址。務必使用開發者工具跟蹤“下載”動作的真實請求。流式下載對于大文件使用resp.iter_content(chunk_size8192)進行流式下載可以避免內存占用過高。Token有效性access_token可能過期通常有幾小時到幾天的有效期。如果腳本運行中途報錯401 Unauthorized就需要重新執行JS偵察步驟獲取新的token。4.4 主函數與流程控制最后我們將上述函數串聯起來并加入一些簡單的進度控制和錯誤記錄。def main(): print( 金山文檔批量下載腳本啟動 ) print(f目標ID: {TARGET_ID}) print(f保存到: {os.path.abspath(SAVE_ROOT)}) # 步驟1獲取所有文件列表 print(\n[步驟1] 正在遍歷文件樹這可能需要一些時間...) all_files get_file_list(TARGET_ID, folder if folder in TARGET_ID else space, ) # 注意TARGET_ID是空間還是文件夾需要判斷這里簡單用字符串判斷可根據實際情況調整。 # 更嚴謹的做法是先用一個API測試ID的類型。 if not all_files: print(未獲取到任何文件請檢查目標ID和Token是否正確。) return print(f\n共發現 {len(all_files)} 個文件。) # 步驟2逐個下載文件 print(\n[步驟2] 開始下載文件...) success_count 0 fail_count 0 fail_list [] for idx, file_info in enumerate(all_files, 1): print(f\n進度: {idx}/{len(all_files)}) if download_file(file_info, SAVE_ROOT): success_count 1 else: fail_count 1 fail_list.append(file_info[name]) # 每個文件下載后稍作停頓避免請求過于密集 time.sleep(1) # 步驟3輸出總結報告 print(\n *50) print(下載任務完成) print(f成功: {success_count} 個) print(f失敗: {fail_count} 個) if fail_list: print(失敗的文件列表:) for name in fail_list: print(f - {name}) print(*50) if __name__ __main__: main()5. 常見問題排查與實戰技巧在實際運行中你幾乎一定會遇到各種問題。下面是我踩過坑后總結的排查清單和應對技巧。5.1 錯誤碼與解決方案速查表錯誤現象可能原因排查步驟與解決方案401 Unauthorized1.ACCESS_TOKEN錯誤或已過期。2.Authorization請求頭格式不對。1.重新獲取Token按3.2步驟在瀏覽器新開一個金山文檔頁面重新獲取最新的access_token。2.檢查格式確保HEADERS字典中Authorization的值是完整的如Bearer eyJ0eX...注意Bearer后面有一個空格。403 Forbidden1. 沒有訪問目標空間的權限。2. Token權限不足。3. 請求頭缺少必要字段如Referer,Origin。1.確認權限確保當前登錄的賬號能訪問該空間。2.補充請求頭在HEADERS中嘗試添加Referer: https://www.kdocs.cn/和Origin: https://www.kdocs.cn。3.降低頻率可能是觸發了風控增加time.sleep的間隔時間。404 Not Found1. API接口地址錯誤。2. 文件或文件夾ID不存在。1.核對API地址使用開發者工具找到正確的API端點并更新BASE_URL。2.檢查ID確認TARGET_ID是否正確是否包含了多余字符。獲取的文件列表為空1.node_type參數錯誤空間/文件夾。2. 分頁邏輯有誤只獲取了第一頁。1.區分空間和文件夾空間用/spaces/{id}/children文件夾用/folders/{id}/children。寫一個判斷函數。2.調試分頁打印每次API請求的響應查看data結構和分頁字段如has_more,total。下載的文件損壞或為0KB1. 下載鏈接是預覽頁而非二進制流。2. 下載請求未攜帶正確的Cookie或簽名參數。1.檢查下載鏈接確保real_download_url是直接指向二進制文件如以.docx、.xlsx結尾或響應頭Content-Type為application/octet-stream。2.攜帶Cookie在下載請求中使用requests.Session()來保持會話或手動設置Cookie頭從瀏覽器復制。腳本中途崩潰1. 網絡不穩定。2. 單個文件下載超時。3. 遇到未處理的異常。1.增加異常捕獲在download_file函數內用更細的try...except包裹。2.實現重試機制對下載失敗的文件記錄到列表腳本最后或單獨重試。3.使用Session用requests.Session()可以提高連接復用和穩定性。5.2 高級技巧與優化建議使用Session保持連接在腳本開頭創建一個requests.Session()對象并用它來發起所有請求。Session會自動處理Cookies且在HTTP長連接上有性能優勢。session requests.Session() session.headers.update(HEADERS) # 然后在make_request函數中使用session.get/post實現斷點續傳對于大批量文件腳本可能因網絡或其它原因中斷。可以設計一個檢查點機制將已成功下載的文件ID記錄到一個JSON文件或數據庫中。每次運行時先加載這個記錄跳過已下載的文件。并發下載提升速度如果文件數量多且單個文件不大可以使用concurrent.futures模塊的ThreadPoolExecutor實現多線程并發下載。但務必注意控制并發數如3-5個線程并妥善處理共享資源如文件寫入避免被封IP。from concurrent.futures import ThreadPoolExecutor, as_completed def download_worker(file_info): return download_file(file_info, SAVE_ROOT) with ThreadPoolExecutor(max_workers3) as executor: future_to_file {executor.submit(download_worker, f): f for f in all_files} for future in as_completed(future_to_file): file_info future_to_file[future] try: result future.result() # 處理結果 except Exception as e: print(f文件 {file_info[name]} 生成異常: {e})更優雅的Token管理將Token等配置信息放在單獨的config.json文件中腳本運行時讀取。甚至可以寫一個小的輔助腳本用Selenium自動登錄并提取Token實現半自動化。處理“蜂窩表格”等特殊類型金山文檔特有的“蜂窩表格”類似多維表可能沒有標準的.xlsx導出格式。其下載鏈接或導出API可能不同。需要單獨分析其網絡請求并可能需要在下載后手動指定后綴名。6. 完整腳本整合與使用步驟將上述所有代碼塊按順序整合到一個.py文件中。以下是清晰的、一步一步的操作指南安裝Python與依賴確保已安裝Python并在終端運行pip install requests。獲取憑證瀏覽器登錄金山文檔進入目標空間/文件夾。按F12打開開發者工具切換到“網絡”(Network)選項卡。觸發文件列表加載如滾動。找到一個list或children類型的API請求從其“請求標頭”中復制Authorization字段的完整值即ACCESS_TOKEN。從瀏覽器地址欄或API響應中復制空間ID或文件夾ID即TARGET_ID。配置腳本用文本編輯器打開kdocs_batch_downloader.py找到開頭的配置區域將ACCESS_TOKEN和TARGET_ID替換為你自己的值。可以調整SAVE_ROOT設置本地保存路徑。運行腳本在終端中切換到腳本所在目錄運行python kdocs_batch_downloader.py。監控與處理腳本會打印遍歷和下載進度。如果中途失敗根據第5部分的排查表檢查。常見的首次運行問題是Token失效或API端點不對請仔細對照開發者工具中的實際請求進行修正。這個方案雖然需要一些手動配置和潛在的調試但它提供了對金山文檔批量下載過程的深度控制避免了瀏覽器自動化工具的笨重和不穩定。一旦跑通你就可以輕松地備份任何你有權限的協作空間了。