01 / 先明确目标
MarkItDown 是微软开源的 Python 文档转换工具，适合把 Word、PDF 等材料整理为便于检索、文本分析和 AI 处理的 Markdown。它不是排版复刻工具，不保证保留原稿的页码、位置和视觉效果。本文依据 2026-09-11 核对的官方文档整理，未进行安装实测；本站交付两份原创 PDF，不含程序本体。
02 / 用小样本建立验收标准
第一次只选一份自己有权处理、不含个人信息的小文件。事先列出三个检查点：正文是否齐全、标题顺序是否合理、表格中数字与单位是否正确。转换成功退出不代表信息完整；必须打开原文件逐项对照。先在副本上试，不要直接覆盖原文件或既有输出。
03 / 独立环境和按需安装
官方要求 Python 3.10 或更高版本，建议使用虚拟环境。先确认 python --version，再在专用目录执行 python -m venv .venv。macOS/Linux 可使用 source .venv/bin/activate；Windows 可直接调用虚拟环境解释器，避免为了激活脚本修改系统执行策略。按格式安装依赖，例如 macOS/Linux：.venv/bin/python -m pip install "markitdown[pdf,docx,pptx]"；Windows：..venv\Scripts\python.exe -m pip install "markitdown[pdf,docx,pptx]"。这是按需安装方案，不包含所有格式支持。
04 / 第一次转换
在已激活环境中运行 markitdown sample.docx -o sample-output.md。未激活时，Windows 使用 ..venv\Scripts\markitdown.exe sample.docx -o sample-output.md；macOS/Linux 使用 .venv/bin/markitdown sample.docx -o sample-output.md。把文件名换成自己的样本，含空格的路径加引号。输出名应是未使用的新文件名。运行后用文本编辑器打开输出，核对正文、列表和关键数字。
05 / 常见问题先分层排查
命令找不到时先确认使用的是同一个虚拟环境。某种格式缺少依赖时，回到官方 optional dependencies 清单补装对应项，不必立即安装全部扩展。扫描件转换为空、表格合并错误或图片没有描述时，不要当作原文没有内容；先检查源文件形态，再选择适合的 OCR 或版式处理路线。本文不承诺扫描件开箱即用。
06 / 默认不接云端、不启用插件
本次入门路线只处理本地样本，不配置云端文档服务、模型客户端或第三方插件。官方提供这些可选能力，但配置后可能发生数据外传和额外计费；需要单独评估服务协议、数据权限和预算。不能因为工具开源，就断言所有处理过程都离线或免费。转换机也不要存放无关客户密钥。
07 / 接入网站前必须增加边界
官方提醒工具使用当前进程权限访问资源。不能把任意用户提交的路径或网址直接送进通用转换入口。实际接入时应限制文件类型、体积、执行时间、可读目录和网络目的地；本地文件场景优先考虑 convert_local()，流式场景考虑 convert_stream()，并独立验证所装版本支持情况。禁止访问服务器密钥目录、内网地址或云元数据地址。转换所得文本仍是不可信内容，不能直接当作 AI 的执行指令。
08 / 批量使用前的检查清单
至少准备纯正文、含表格和含图片三类授权样本，分别记录遗漏、乱码和结构变化。保留输入、输出、所用版本及错误日志，日志中不要包含敏感原文。只把验证通过的格式纳入批处理；重要数值仍需人工复核。官方最新正式 Release 核对为 v0.1.7（2026-07-29）；主分支文档可能比该版更快更新，安装和依赖以实际版本为准。