【实战案例 5】MarkItDown API 服务

项目背景

需求：

将 Word、PDF、PPT 等文件转换为 Markdown 格式。

技术选型：

后端：Node.js + Express
转换核心：Microsoft Markitdown (Python)
部署：Replit

实现步骤

第 1 步：Python 转换脚本

convert.py：


import sys
import json
from markitdown import MarkItDown
 
def convert_file(file_path):
    try:
        md = MarkItDown()
        result = md.convert(file_path)
        return {
            "success": True,
            "markdown": result.text_content
        }
    except Exception as e:
        return {
            "success": False,
            "error": str(e)
        }
 
if __name__ == "__main__":
    file_path = sys.argv[1]
    result = convert_file(file_path)
    print(json.dumps(result))

第 2 步：Node.js API 服务器

server.js：


const express = require('express');
const multer = require('multer');
const { spawn } = require('child_process');
const fs = require('fs');
const path = require('path');
 
const app = express();
const PORT = process.env.PORT || 3000;
 
// 配置文件上传
const storage = multer.diskStorage({
  destination: './uploads/',
  filename: (req, file, cb) => {
    cb(null, Date.now() + '-' + file.originalname);
  }
});
 
const upload = multer({
  storage: storage,
  limits: { fileSize: 10 * 1024 * 1024 } // 限制 10MB
});
 
// 确保上传目录存在
if (!fs.existsSync('./uploads')) {
  fs.mkdirSync('./uploads');
}
 
// 转换接口
app.post('/api/convert', upload.single('file'), async (req, res) => {
  if (!req.file) {
    return res.status(400).json({
      success: false,
      message: '请上传文件'
    });
  }
 
  const filePath = req.file.path;
 
  try {
    // 调用 Python 脚本
    const python = spawn('python3', ['convert.py', filePath]);
 
    let result = '';
    let error = '';
 
    python.stdout.on('data', (data) => {
      result += data.toString();
    });
 
    python.stderr.on('data', (data) => {
      error += data.toString();
    });
 
    python.on('close', (code) => {
      // 删除临时文件
      fs.unlinkSync(filePath);
 
      if (code !== 0) {
        return res.status(500).json({
          success: false,
          message: '转换失败',
          error: error
        });
      }
 
      try {
        const jsonResult = JSON.parse(result);
        res.json(jsonResult);
      } catch (e) {
        res.status(500).json({
          success: false,
          message: '解析结果失败',
          error: e.message
        });
      }
    });
  } catch (error) {
    // 清理文件
    if (fs.existsSync(filePath)) {
      fs.unlinkSync(filePath);
    }
 
    res.status(500).json({
      success: false,
      message: error.message
    });
  }
});
 
// 健康检查
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});
 
app.listen(PORT, () => {
  console.log(`MarkItDown API 运行在端口 ${PORT}`);
});

第 3 步：package.json


{
  "name": "markitdown-api",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.18.2",
    "multer": "^1.4.5-lts.1"
  }
}

第 4 步：部署到 Replit

在 Replit 创建新项目（Node.js）
上传所有文件
在 Shell 中安装 Python 依赖：
```
pip install markitdown
```
点击「Run」

第 5 步：测试

使用 curl：


curl -X POST https://your-repl.repl.co/api/convert \
  -F "[email protected]"

响应：


{
  "success": true,
  "markdown": "# 文档标题\n\n这是文档内容..."
}

使用 AI 辅助开发

Cursor 提示词：完整项目生成


我想开发一个完整的项目，需求如下：

【项目信息】
- 项目名称：[名称]
- 项目类型：[网站/插件/API服务]
- 技术栈：[前端+后端技术]

【核心功能】
1. [功能1详细描述]
2. [功能2详细描述]
3. [功能3详细描述]

【技术要求】
- 前端：[React/Next.js/原生]
- 后端：[Node.js/Python]
- 数据库：[需要/不需要]
- 部署：[Vercel/Replit/其他]

【API设计】（如果需要）
GET /api/xxx - [说明]
POST /api/xxx - [说明]

【界面要求】（如果需要）
- 布局：[描述]
- 样式：[Tailwind CSS / 自定义]
- 响应式：[需要/不需要]

请帮我：
1. 生成完整的项目结构
2. 提供所有必要文件的代码
3. 添加详细注释
4. 提供部署和测试说明
5. 列出可能遇到的问题和解决方案

本章小结

恭喜完成第 5 章学习！现在你已经掌握：

技能清单

✅ Chrome 插件开发（Manifest V3）
✅ Node.js 后端开发
✅ RESTful API 设计
✅ 环境变量管理
✅ 错误处理和日志
✅ 模块化开发
✅ 前后端调试技巧
✅ 部署到 Replit

实战项目

✅ TabMagnet 标签管理插件
✅ MarkItDown API 转换服务
✅ Todo List API
✅ 网页划词搜索插件

下一步

第 6 章预告：部署上线与运营

Git 版本管理
GitHub 代码托管
Vercel 一键部署
域名购买与配置
Google Analytics 数据分析
SEO 优化技巧

现在你可以：

尝试修改 TabMagnet，添加更多功能
为 MarkItDown API 添加更多文件格式支持
开发自己的第一个产品

记住：

编程的本质是解决问题，而不是死记语法。遇到问题，先 Google，再问 AI，最后问人。

上线了什么新玩意儿，别闷在电脑里，发到朋友圈/社区收集反馈，迭代思路往往就来自这些声音。

继续前进！ 🚀