pptopic 说明

将 PowerPoint 演示文稿导出为长图的工具。

功能

• 将 PPTX 文件的所有幻灯片垂直拼接为一张长图
• 支持 JPG 和 PNG 格式输出
• 支持自定义输出宽度和目录
• 内置图片优化功能，使用图片优化引擎进行无损压缩

系统要求

• Windows 系统（使用 win32com 调用 PowerPoint）
• Python >= 3.13
• Microsoft PowerPoint

新手使用说明

如果你是第一次使用命令行工具，请按以下步骤操作。我们提供了一键安装脚本，尽量让你少输入命令。

安装前准备

• PowerPoint：需要安装 Microsoft PowerPoint（Office 2016 或更新版本）
• 网络连接：安装过程中需要下载工具
• 解压项目：把下载的 pptopic.zip 解压到任意位置，例如桌面

一键安装（推荐）

项目根目录下有一个 setup.bat，它会自动完成：

1. 安装 uv（Python 包管理器）
2. 安装 Python 3.13
3. 安装 pngquant（图片压缩工具，强烈推荐）
4. 安装 pptopic
5. 验证安装结果

方法 A：双击运行（最简单）

1. 打开解压后的 pptopic 文件夹
2. 找到 setup.bat 文件
3. 双击 setup.bat
4. 等待安装完成，窗口会显示版本信息

如果 Windows 提示“Windows 已保护你的电脑”，请点击“更多信息” → “仍要运行”。

方法 B：右键在终端中运行

如果双击运行被系统拦截，可以按以下步骤：

1. 打开解压后的 pptopic 文件夹
2. 在文件夹空白处按住 Shift 键，同时点击鼠标右键
3. 选择“在此处打开 PowerShell 窗口”（Windows 11 可能显示为“在终端中打开”）
4. 在弹出的窗口中输入以下命令，然后按回车：

.\setup.bat

打开的终端可能是 PowerShell（蓝色窗口）或命令提示符 cmd（黑色窗口），两种情况下 .\setup.bat 都能正常运行。如果是 cmd，也可以省略前面的 .\ 直接输入 setup.bat。

等待安装完成即可。

安装完成后

如果看到类似下面的输出，说明安装成功：

--- uv 版本 ---
uv 0.11.20

--- pngquant 版本 ---
2.17.0

--- pptopic 版本 ---
pptopic version: 0.3.2
Under the MIT License.

--- PowerPoint 检测 ---
PowerPoint 已安装（检测到 PowerPoint.Application 注册项）。

如果你没有安装 PowerPoint，最后一行会显示警告，提示你先安装 PowerPoint，否则 pptopic export 命令无法运行。

然后你可以直接在当前窗口使用 pptopic：

# 导出 PPTX 为长图
pptopic export presentation.pptx

# 工作中常用命令：导出 PPTX 为长图并优化图片
# 其中，29999 是微信接受的最大高度
pptopic export presentation.pptx --optimize --max-height 29999 -o result.png

一键安装脚本的参数（可选）

如果你不想安装 pngquant，可以使用以下方式运行：

# 在 PowerShell 中直接运行 setup.ps1，跳过 pngquant
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -SkipPngquant

其他可用参数：

• -SkipPngquant：跳过 pngquant 安装
• -Force：强制重新安装 uv 和 pngquant
• -SkipPptopicInstall：只安装环境，不安装 pptopic

手动安装（备用）

如果一键安装脚本在你的电脑上无法运行，可以按以下步骤手动安装。

第一步：安装 uv

uv 是一个 Python 包管理器，用来安装 pptopic 及其依赖。

打开 PowerShell（在开始菜单搜索 "PowerShell"），进入本项目的目录：

cd "<你的解压目录>\pptopic"

赋予 PowerShell 执行权限：

Set-ExecutionPolicy Bypass -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

运行项目自带的安装脚本：

.\uv-installer.ps1

该脚本会自动下载最新版本的 uv 并添加到系统 PATH。如果你在中国大陆，脚本已内置 GitHub 加速镜像，无需额外配置。

安装完成后，关闭并重新打开 PowerShell，验证安装：

uv --version

• 如果你已安装 scoop，也可以直接 scoop install uv。
• 如果想安装特定版本的 uv，可以在运行脚本前设置环境变量：$env:UV_INSTALLER_VERSION = "0.11.20"

第二步：安装 Python

使用 uv 安装 Python 3.13 或更新版本：

uv python install 3.13

第三步（可选）：安装 pngquant 图片优化工具

虽然是可选安装，但我超级建议你安装，因为 ppt 导出后，图片通常较大，不进行图片无损压缩，会导致文件大小过大。

如果你需要对导出的图片进行压缩优化，运行：

.\install-pngquant.ps1

该脚本会：

1. 如果你已安装 scoop → 通过 scoop 安装 pngquant
2. 如果没有 scoop → 自动下载并安装到 %APPDATA%\pngquant，并添加到 PATH

安装完成后，重新打开 PowerShell，验证安装：

pngquant --version

• 自定义安装目录：.\install-pngquant.ps1 -InstallDir "D:\Tools\pngquant"
• 强制重新安装：.\install-pngquant.ps1 -Force

第四步：安装 pptopic

uv tool install -e .

第五步：开始使用

# 导出 PPTX 为长图
pptopic export presentation.pptx

# 优化图片
pptopic optimize image.png

# 工作中常用命令：导出 PPTX 为长图并优化图片
# 其中，29999 是微信接受的最大高度
pptopic export presentation.pptx --optimize --max-height 29999 -o result.png

至此安装完成。

一般安装说明

安装 pptopic

git clone https://git.lyz.one/SidneyZhang/pptopic.git
cd pptopic
uv tool install -e .

安装 uv

项目使用 uv 进行安装和项目管理，如果你没有安装，这里提供一个简单的安装指引：

只是简单安装，可以使用项目自带的安装脚本（推荐）：

.\uv-installer.ps1

该脚本自动检测 uv 最新版本，支持国内 GitHub 加速镜像下载（mirror.ghproxy.com、ghproxy.net），并自动将 uv 添加到系统 PATH。

也可以通过 scoop 安装：

scoop install uv

或者使用官方提供的安装脚本：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

请注意，上述脚本都需要相关的脚本运行权限，否则无法正常运行，一般如下操作即可获取相关权限：

Set-ExecutionPolicy Bypass -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

使用

导出 PPTX 为长图

# 基本用法
pptopic export presentation.pptx

# 详细说明
pptopic export --help

单独优化图片

# 优化图片
pptopic optimize image.png

# 详细说明
pptopic optimize --help

图片优化引擎

为了获得最佳的图片压缩效果，推荐使用 pngquant 进行图片压缩。 当然也可以使用其他图片压缩工具，如 libvips 等，不过需要自己设置引擎的优化参数。

PngQuant安装脚本

可以使用提供的 PowerShell 脚本安装 pngquant：

.\install-pngquant.ps1

该脚本支持两种安装方式：

1. 已安装 scoop → 通过 scoop install pngquant 安装
2. 未安装 scoop → 从 pngquant 官网下载并安装到 %APPDATA%\pngquant，自动添加到 PATH

# 自定义安装目录
.\install-pngquant.ps1 -InstallDir "D:\Tools\pngquant"

# 强制重新安装
.\install-pngquant.ps1 -Force

# 不修改 PATH ，将无法全局使用这个工具
.\install-pngquant.ps1 -NoModifyPath

也可以直接使用 scoop 安装 pngquant，或者手动下载安装。

scoop install pngquant

或从 pngquant.org 下载 Windows 版本手动配置。

常见问题

运行 setup.bat 时提示“无法加载文件，因为在此系统上禁止运行脚本”

这说明当前电脑通过组策略严格限制了脚本执行。setup.bat 已经尝试用 -ExecutionPolicy Bypass 绕过，但仍可能被拦截。

解决方法：使用 方法 B，在 PowerShell 窗口中手动运行：

powershell -ExecutionPolicy Bypass -File .\setup.ps1

不需要以管理员身份运行，本安装脚本只修改当前用户的环境变量。

安装完成后关闭窗口，新窗口中找不到 pptopic 命令

请重新运行一次 setup.bat。如果问题依旧，请检查系统环境变量中的 PATH 是否包含以下目录：

• %USERPROFILE%\.local\bin（uv 和 pptopic 的位置）
• %APPDATA%\pngquant（pngquant 的位置）

不想安装 pngquant 怎么办？

可以运行：

powershell -ExecutionPolicy Bypass -File .\setup.ps1 -SkipPngquant

但强烈建议安装，否则导出的长图文件会比较大。

安装时报“未检测到 PowerPoint”

安装脚本会在最后一步检测 PowerPoint 是否安装。如果看到这个警告，说明系统里没有 PowerPoint，pptopic export 命令将无法运行（它需要通过 PowerPoint 导出幻灯片）。

请安装 Microsoft PowerPoint（Office 2016 或更新版本）后重试。PowerPoint 不在一键安装脚本的自动安装范围内，需要自行安装。

License

MIT License