自定义命令的Typora图片上传工具

在使用Markdown进行写作时，图片的处理一直是一个需要解决的问题。尤其对于博客作者、技术文档撰写者来说，如何高效地管理和引用图片资源至关重要。Typora作为一款优秀的Markdown编辑器，虽然提供了基本的图片插入功能，但在图片上传和管理方面仍有提升空间。本文将介绍一个专为Typora开发的图片上传工具，它能够帮助你轻松将图片上传到指定服务器，并自动替换文档中的图片链接。

工具项目地址：项目首页 - typora-image-uploader - GitCode

一、工具概述

1.1 功能特点

这款Typora图片上传工具具有以下核心功能：

  • 自定义上传服务器：可以将图片上传到你指定的任何服务器
  • HTTP代理支持：适用于需要通过代理访问外部网络的环境
  • 认证令牌支持：提供安全的上传认证机制
  • 简单易用：与Typora无缝集成，操作简便
  • 多平台支持：提供Python和PHP两种服务器端实现方案

1.2 工作原理

该工具的工作流程非常直观：

  1. 当你在Typora中插入图片时（通过拖拽、粘贴或菜单插入）
  2. Typora调用配置好的自定义命令（即我们的上传脚本）
  3. 脚本将图片上传到指定的服务器
  4. 服务器返回图片的URL，脚本将URL返回给Typora
  5. Typora自动将本地图片路径替换为服务器URL

QQ20250608-180927

整个过程对用户来说是透明的，插入图片后几秒钟内就能看到图片被上传并显示出来。

二、安装与配置

2.1 安装要求

在开始之前，请确保你的环境满足以下要求：

客户端要求： - Python 3.6或更高版本 - requests库

服务器端要求（根据你选择的实现方式）：
- Python版本：Python 3.6+，Flask框架
- PHP版本：PHP 7.0+

2.2 客服端安装步骤

  • 因为自定义的是调用py的命令，首先，确保你已安装Python 3.6或更高版本。
    下载并安装win或mac版的python 可以通过以下命令检查：python --version
  • 安装必要的依赖库：pip install requests
  • 把typora_uploader.py脚本放到客户端本地。你可以将它放在任何方便访问的位置，
    例如：D:\typimage\typora_uploader.py

2.3 初始化配置(可选)

在使用工具之前，如果需要，可以进行一次初始化配置：

  • 打开命令提示符或终端
  • 运行以下命令：python typora_uploader.py --init
  •  按照提示输入以下信息：
    • 上传服务器URL：接收图片上传的服务器地址，
      例如：http://your-server.com/upload
    • 认证令牌：用于服务器认证的令牌（如果服务器需要）
    • 文件字段名：服务器接收文件的字段名（默认为"file"）
    • 超时时间：上传超时时间（秒），建议设置为30-60秒
    • URL前缀：如果服务器返回的是相对路径，可以设置URL前缀，
      例如：https://your-server.com/

完成配置后，工具会自动创建配置文件并保存在用户目录下的.typora-upload/config.json中。

当然也可以不用创建配置文件步骤，将会使用默认配置

# typora_uploader.py 默认配置
DEFAULT_CONFIG = {
    "server": {
        "url": "https://your-server.com/upload",  # 上传服务器URL
        "token": "",                        # 认证令牌
        "field_name": "file"                # 文件字段名
    },
    "proxy": "",                           # 代理设置，如 http://127.0.0.1:7890
    "timeout": 30,                          # 超时时间(秒)
    "url_prefix": ""                       # URL前缀，用于拼接返回的URL
}

2.4 配置Typora编辑器

接下来，需要在Typora中配置图片上传功能：

  1. 打开Typora编辑器
  2. 进入「文件」→「偏好设置」→「图像」
  3. 在「插入图片时...」选项中选择「上传图片」
  4. 在「图像上传设置」中选择「自定义命令」

  5. 在「命令」输入框中填入：python 完整路径\typora_uploader.py 例如：python D:\typimage\typora_uploader.py

  6. 点击「测试上传」按钮，验证配置是否正确 如果测试成功（需要完成后面的服务端配置后） ，
    你会看到一条成功消息，并且测试图片的URL会显示在对话框中。
    QQ20250608-181206

三、使用方法

3.1 日常使用

完成上述配置后，使用方法非常简单：

  1. 在Typora中编辑Markdown文档
  2. 通过以下任一方式插入图片：
  3. 直接拖拽图片到编辑器中
  4. 复制图片后在编辑器中粘贴（Ctrl+V）
  5. 使用「格式」→「图像」→「插入图片」菜单
  6. 稍等片刻，图片会自动上传并显示 插入图片后，Typora会先显示本地图片路径，然后在上传完成后自动替换为服务器URL。
    整个过程通常只需几秒钟。

四、服务器端设置

4.1 PHP版本服务器

如果你选择使用PHP实现服务器端，步骤如下：

  • 确保你的Web服务器（如Apache、Nginx）已安装PHP 7.0+

  • 把server_example.php文件放在Web服务器可以访问到的目录下，

  • 创建uploads目录，并确保uploads目录可写：
    chmod 777 uploads # Linux/Mac环境
    // server_example.php 配置上传文件夹
    $uploadFolder = '/home/your-server.com/uploads';

  • 配置Apache：关键是RewriteRule ^upload $ server_example.php [L]
    Nginx 自己写或借助ai写一下。
    RewriteRule ^upload$ server_example.php [L]
  • 访问你的Web服务器地址，例如：http://localhost/server_example.php

4.2 Python版本服务器

如果你选择使用Python实现服务器端，步骤如下：

  • 安装Flask框架：pip install flask
  • 把server_example.py文件放在Web服务器可以访问到的目录下
  • 运行服务器：python server_example.py

服务器将在 http://localhost:8000 上启动，上传端点为 http://localhost:8000/upload

五、高级功能与自定义

5.1 自定义响应解析

默认情况下，工具期望服务器返回以下JSON格式：

{
  "url": "https://example.com/uploads/uploaded.png"
}

如果你的服务器返回不同格式的响应，可以修改typora_uploader.py中的upload_image函数来适配。

5.2 支持其他图床

要支持其他图床（如七牛云、阿里云OSS、GitHub等），你可以修改上传逻辑。
例如，添加对特定图床API的支持：

def upload_to_qiniu(file_path, config):
    # 实现七牛云上传逻辑
    pass

def upload_to_github(file_path, config):
    # 实现GitHub上传逻辑
    pass

然后在配置中添加图床类型选项，根据选择调用不同的上传函数。

5.3 图片压缩与处理

你可以在上传前添加图片处理功能，如压缩、调整大小、添加水印等：

from PIL import Image

def process_image(file_path, max_width=800):
    # 打开图片
    img = Image.open(file_path)

    # 调整大小
    width, height = img.size
    if width > max_width:
        ratio = max_width / width
        new_height = int(height * ratio)
        img = img.resize((max_width, new_height), Image.LANCZOS)

    # 保存处理后的图片
    img.save(file_path, optimize=True, quality=85)

    return file_path

在上传前调用此函数处理图片。

六、故障排除

6.1 常见问题与解决方案

  1. 上传失败，无响应
    • 检查网络连接
    • 验证服务器URL是否正确
    • 检查防火墙设置

  2. 认证失败

    • 确认认证令牌是否正确

    • 检查服务器端认证逻辑

  3. 文件类型错误

    • 确认服务器允许上传的文件类型

    • 检查文件扩展名是否正确

  4. 文件大小超限

    • 检查服务器端文件大小限制
    • 对于PHP服务器，检查php.ini中的upload_max_filesize和post_max_size设置

七、总结与展望

7.1 工具优势

这个Typora图片上传工具通过简单的配置，为Markdown写作提供了强大的图片管理能力：

  • 提高写作效率：无需手动上传图片并复制链接
  • 灵活的服务器选择：可以使用自己的服务器或第三方图床
  • 安全可靠：支持认证和HTTPS
  • 易于扩展：可以根据需要自定义功能

7.2 未来改进方向

这个工具还有很多可以改进的地方（你可以自行使用trae借助ai进行开发，只需要把本工具的文件放在开发项目的目录中，提出需求ai会自己扩展功能或改进。）：

  1. 图形界面配置：开发一个GUI配置工具，使配置更加直观
  2. 多图床支持：内置更多常用图床的支持
  3. 图片管理功能：添加已上传图片的管理、删除功能
  4. 智能重试机制：在上传失败时自动重试
  5. 批量迁移工具：在不同图床之间迁移已上传的图片

八、许可证

本工具采用MIT许可证开源，你可以自由使用、修改和分发，但需保留原始许可证和版权信息。

通过这个自定义的Typora图片上传工具，你可以大大简化Markdown写作中的图片处理流程，专注于内容创作而不是技术细节。无论是撰写技术博客、文档还是笔记，它都能成为你的得力助手。

如果你有任何问题或改进建议，欢迎在项目仓库中提出issue或贡献代码。让我们一起让Markdown写作变得更加高效和愉快！