Python+JS混合方案：破解金山文档批量下载难题

1. 项目缘起与核心痛点

最近在整理团队资料时，遇到了一个非常具体且磨人的需求：需要把金山文档里一个包含了几百个文件的协作空间，全部下载到本地进行归档和备份。这个需求听起来简单，但实际操作起来，你会发现金山文档官方并没有提供一个“一键打包下载”的功能。你只能一个个文件点开，再手动选择“下载为”某种格式，效率低到令人发指，而且极其容易出错或遗漏。这让我想起了以前处理类似办公文档批量操作时的经历，比如处理Excel表格或者Word文档，但金山文档作为一个在线协作平台，它的文件存储和访问逻辑又有些不同。

这个“坑”的本质在于，金山文档的在线文件系统是动态加载的，其文件列表和下载链接并非静态呈现，而是通过JavaScript动态渲染和接口调用来完成的。这就意味着，传统的、简单的HTTP请求抓取页面HTML的方式行不通。你需要模拟浏览器的行为，或者直接与它的后端API进行“对话”。我的目标很明确：写一个脚本，能自动登录（或使用已有登录态）、遍历指定文件夹下的所有文件、识别文件类型（文档、表格、幻灯片等）、并批量下载到本地，且最好能保持原有的文件名和目录结构。

经过一番摸索和尝试，我最终组合使用了Python和浏览器开发者工具中的JavaScript，形成了一套相对稳定且可复现的解决方案。Python负责整体的流程控制、网络请求和文件操作，而JS代码（主要通过复制粘贴到浏览器控制台执行）则用于在已登录的页面上下文中，快速获取那些受保护的API令牌和文件列表信息。下面，我就把这套方法的核心思路、踩过的坑以及完整的操作步骤记录下来。

2. 技术方案选型与思路拆解

面对金山文档这种复杂的单页应用（SPA），直接上手写Python爬虫往往会碰壁。我们需要先理解它的数据流。

2.1 为什么是Python + JS的组合？

纯Python方案（如requests+BeautifulSoup）在遇到大量JS渲染和反爬机制时，会变得非常笨重。你需要处理Cookie、Token、动态参数，甚至可能模拟整个登录流程和页面交互，复杂度极高。

纯浏览器自动化方案（如Selenium或Playwright）可以完美模拟用户操作，但缺点也很明显：速度慢、资源占用高、不够稳定，且难以进行精细化的错误处理和流程控制。

因此，我采用的是一种“混合动力”方案：

1. JS探路：利用浏览器开发者工具（F12），在已经手动登录的金山文档页面中，执行一些简短的JS代码片段。这些代码运行在页面的真实上下文中，可以轻松访问到页面内嵌的API令牌、用户信息以及通过XHR/Fetch加载的原始JSON数据。这一步的目的是“侦察”，获取那些对Python脚本至关重要的密钥（如access_token）和数据结构。
2. Python主攻：拿到JS侦察兵获取的关键信息后，用Python编写主脚本。Python脚本使用requests库，携带这些令牌，直接调用金山文档的后端API接口，进行文件列表的获取和文件下载。这样既绕开了复杂的页面渲染，又保证了效率和稳定性。

这个组合的核心优势在于：JS用于在“信任环境”（已登录的浏览器）中安全地获取凭证；Python利用这些凭证进行高效、批量的自动化操作。两者分工明确，各取所长。

2.2 核心流程设计

整个批量下载流程可以分解为以下几个关键环节，我画了一个简单的思维导图来帮助理解：

开始 │ ├─ 环节1：人工介入，浏览器登录金山文档 │ (获取登录态Cookie) │ ├─ 环节2：JS侦察，获取关键令牌(access_token)和空间/文件夹ID │ (在浏览器控制台执行代码) │ ├─ 环节3：Python主脚本启动 │ │ │ ├─ 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）。

1. 登录并打开目标空间：用你的浏览器（Chrome/Firefox/Edge均可）正常登录金山文档，并进入你想要批量下载的那个“协作空间”或“文件夹”的页面。

2. 打开开发者工具：按F12打开开发者工具，切换到“网络”(Network)选项卡。为了清晰，可以先点击垃圾桶图标清空之前的记录。

3. 触发一次文件列表加载：在页面左侧的文件列表区域，尝试滚动或点击进入某个子文件夹，让浏览器发起网络请求。

4. 寻找关键请求：在“网络”选项卡中，你会看到很多请求。寻找一个类型为fetch或xhr，名称看起来像list或children的请求，其URL可能包含https://www.kdocs.cn/api/v3/这样的路径。点击这个请求，查看它的“标头”(Headers)和“响应”(Response)。

5. 提取access_token：

   • 在“标头”部分，找到“请求标头”下的Authorization字段。它的值通常是Bearer eyJ...这样一长串字符。eyJ开头的部分就是你的access_token。复制它。
   • 重要：这个token具有你的账户权限，请像保管密码一样妥善保管，不要泄露。

6. 提取空间或文件夹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。

7. 使用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_ok=True) def make_request(url, method='GET', params=None, data=None): """封装请求函数，添加重试和错误处理""" try: if method.upper() == 'GET': resp = requests.get(url, headers=HEADERS, params=params, timeout=30) else: resp = requests.post(url, headers=HEADERS, json=data, timeout=30) 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_type='folder', 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, params=params) 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参数循环请求，直到获取所有数据。limit=100是常见的最大值。
• 路径处理：我们为每个文件计算了一个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_ok=True) # 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, stream=True, timeout=60) resp.raise_for_status() with open(local_file_path, 'wb') as f: for chunk in resp.iter_content(chunk_size=8192): 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_size=8192)进行流式下载，可以避免内存占用过高。
• 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 错误码与解决方案速查表

5.2 高级技巧与优化建议

1. 使用Session保持连接：在脚本开头创建一个requests.Session()对象，并用它来发起所有请求。Session会自动处理Cookies，且在HTTP长连接上有性能优势。

   session = requests.Session() session.headers.update(HEADERS) # 然后在make_request函数中使用session.get/post

2. 实现断点续传：对于大批量文件，脚本可能因网络或其它原因中断。可以设计一个检查点机制，将已成功下载的文件ID记录到一个JSON文件或数据库中。每次运行时先加载这个记录，跳过已下载的文件。

3. 并发下载提升速度：如果文件数量多且单个文件不大，可以使用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_workers=3) 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}")

4. 更优雅的Token管理：将Token等配置信息放在单独的config.json文件中，脚本运行时读取。甚至可以写一个小的辅助脚本，用Selenium自动登录并提取Token，实现半自动化。

5. 处理“蜂窝表格”等特殊类型：金山文档特有的“蜂窝表格”（类似多维表）可能没有标准的.xlsx导出格式。其下载链接或导出API可能不同。需要单独分析其网络请求，并可能需要在下载后手动指定后缀名。

6. 完整脚本整合与使用步骤

将上述所有代码块按顺序整合到一个.py文件中。以下是清晰的、一步一步的操作指南：

1. 安装Python与依赖：确保已安装Python，并在终端运行pip install requests。
2. 获取凭证：
   • 浏览器登录金山文档，进入目标空间/文件夹。
   • 按F12打开开发者工具，切换到“网络”(Network)选项卡。
   • 触发文件列表加载（如滚动）。
   • 找到一个list或children类型的API请求，从其“请求标头”中复制Authorization字段的完整值（即ACCESS_TOKEN）。
   • 从浏览器地址栏或API响应中，复制空间ID或文件夹ID（即TARGET_ID）。
3. 配置脚本：用文本编辑器打开kdocs_batch_downloader.py，找到开头的配置区域，将ACCESS_TOKEN和TARGET_ID替换为你自己的值。可以调整SAVE_ROOT设置本地保存路径。
4. 运行脚本：在终端中，切换到脚本所在目录，运行python kdocs_batch_downloader.py。
5. 监控与处理：脚本会打印遍历和下载进度。如果中途失败，根据第5部分的排查表检查。常见的首次运行问题是Token失效或API端点不对，请仔细对照开发者工具中的实际请求进行修正。

这个方案虽然需要一些手动配置和潜在的调试，但它提供了对金山文档批量下载过程的深度控制，避免了浏览器自动化工具的笨重和不稳定。一旦跑通，你就可以轻松地备份任何你有权限的协作空间了。