5个步骤教你制作QtScrcpy跨平台绿色版

一、需求分析：为什么需要绿色版

绿色版（便携版）是指无需安装、解压即可运行的软件版本，特别适合需要在多台设备间频繁迁移的用户。对于QtScrcpy这类Android控制工具，绿色版具有三大核心价值：无需管理员权限即可使用、配置文件随目录迁移、避免系统环境差异导致的运行问题。

制作绿色版的本质是依赖打包——将Qt运行库、ADB工具、Scrcpy服务器及配置文件等所有必要组件整合到单一目录中。QtScrcpy项目已提供完善的CI构建脚本，我们只需在此基础上优化打包逻辑。

核心要点：

• 绿色版需包含可执行文件、Qt库、ADB工具、Scrcpy服务器四部分
• 配置文件应保存在应用目录下（config/config.ini(v2.1+)）
• 不同平台依赖处理方式差异较大，需针对性设计打包策略

二、方案设计：绿色版架构与实现路径

2.1 整体架构设计

绿色版采用"核心程序+依赖库+资源文件"的三层架构：

• 核心层：QtScrcpy可执行文件及Scrcpy服务器
• 依赖层：Qt运行库、ADB工具链、系统运行时组件
• 资源层：按键映射配置（keymap/）、UI资源（res/）、用户配置（config/）

2.2 跨平台实现策略

平台	打包格式	依赖处理工具	核心脚本	分发体积
Windows	压缩包	windeployqt	ci/win/publish_for_win.bat	~60MB
Linux	AppImage	linuxdeploy	ci/linux/package_appimage.sh	~80MB
macOS	DMG镜像	macdeployqt	ci/mac/package_for_mac.sh	~75MB

核心要点：

• Windows需重点处理Visual C++运行时依赖
• Linux采用AppImage格式实现跨发行版兼容
• macOS通过DMG镜像简化用户使用流程
• 所有平台均需保留config/和keymap/目录的可写权限

三、多平台实现：分步骤操作指南

3.1 Windows平台：通过批处理脚本实现依赖自动打包

环境检查清单：

• 硬件：x86_64架构CPU，至少2GB内存
• 软件：Visual Studio 2022、Qt 5.15+、CMake 3.20+

实现步骤：

1. 编译项目

   :: 设置编译参数
   set cmake_params=-DCMAKE_PREFIX_PATH=%qt_cmake_path% -DCMAKE_BUILD_TYPE=Release
   :: 生成解决方案
   cmake %cmake_params% ../..
   :: 并行构建
   cmake --build . --config Release -j8
   

2. 收集依赖

   :: 创建发布目录
   mkdir publish
   :: 复制主程序及资源
   xcopy Release\QtScrcpy.exe publish\ /Y
   xcopy ..\..\adb\adb.exe publish\ /Y
   xcopy ..\..\server\scrcpy-server publish\ /Y
   xcopy ..\..\keymap publish\keymap\ /E /Y
   :: 自动部署Qt依赖
   windeployqt publish\QtScrcpy.exe
   

3. 精简优化

   :: 删除非必要插件
   rmdir /s/q publish\iconengines
   del publish\imageformats\qgif.dll
   :: 保留截图必需的jpeg插件
   :: 保留核心Qt库：Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll
   

核心要点：

• 使用windeployqt自动分析并复制Qt依赖
• 必须保留qjpeg.dll以支持截图功能
• 需手动添加vcruntime140.dll等Visual C++运行时组件

3.2 Linux平台：AppImage格式实现跨发行版兼容

环境检查清单：

• 硬件：x86_64架构CPU
• 软件：Qt 5.15+、linuxdeploy、AppImageTool

实现步骤：

1. 准备工作

   # 检测Qt安装路径
   common_qt_paths=("$HOME/Qt" "/opt/Qt" "/usr/lib/qt5")
   for path in "${common_qt_paths[@]}"; do
     if [ -d "$path" ]; then
       ENV_QT_PATH="$path/$(ls -1t $path | head -1)/gcc_64"
       break
     fi
   done
   

2. 构建AppDir结构

   mkdir -p appdir/usr/bin appdir/usr/lib
   # 复制主程序
   cp build/QtScrcpy appdir/usr/bin/
   # 复制资源文件
   cp -r keymap appdir/usr/share/
   cp -r config appdir/usr/share/
   

3. 生成AppImage

   # 处理Qt依赖
   export QMAKE="$ENV_QT_PATH/bin/qmake"
   linuxdeploy --appdir appdir --plugin qt --output appimage
   # 重命名输出文件
   mv QtScrcpy-x86_64.AppImage QtScrcpy-green-x86_64.AppImage
   

核心要点：

• AppImage格式可在Ubuntu、Fedora等主流发行版直接运行
• 使用linuxdeploy自动处理动态库依赖
• 赋予执行权限：chmod +x QtScrcpy-green-x86_64.AppImage

3.3 macOS平台：DMG镜像实现拖拽式安装

环境检查清单：

• 硬件：Intel或Apple Silicon芯片Mac
• 软件：Xcode 12+、Qt 5.15+、create-dmg工具

实现步骤：

1. 编译应用

   # 设置Qt环境
   export PATH="$HOME/Qt/5.15.2/clang_64/bin:$PATH"
   # 构建项目
   qmake QtScrcpy.pro
   make -j8
   

2. 打包应用

   # 生成.app包
   macdeployqt QtScrcpy.app -dmg
   # 自定义DMG外观
   python ci/mac/package/package.py
   

3. 签名与验证

   # 可选：对应用进行签名
   codesign --deep --force --sign "Developer ID Application" QtScrcpy.app
   

核心要点：

• DMG镜像本身就是绿色分发格式
• 使用macdeployqt处理框架依赖
• Apple Silicon用户需确保Qt版本支持ARM架构

四、优化策略：减小体积与提升兼容性

4.1 体积优化技巧

💡 关键优化点：

1. 依赖精简：仅保留必要Qt模块（Core、Gui、Widgets、Network）
2. 资源压缩：使用UPX压缩可执行文件（Windows: upx --best QtScrcpy.exe）
3. 文件清理：删除调试符号、文档和示例文件
4. 格式转换：将PNG图标转换为SVG格式减少体积

4.2 兼容性增强

⚠️ 兼容性处理：

1. Windows：同时提供32位和64位版本
2. Linux：基于Ubuntu 18.04构建以保证向下兼容
3. macOS：支持10.14+版本，区分Intel和Apple Silicon架构

优化效果对比：

优化措施	原始体积	优化后体积	减少比例
基础打包	120MB	85MB	29%
依赖精简	85MB	68MB	20%
可执行文件压缩	68MB	52MB	23%

五、问题排查：常见故障解决方案

5.1 依赖缺失问题

症状	原因	解决方案
启动时报"找不到Qt5Core.dll"	Qt运行库未正确打包	重新运行windeployqt或手动复制Qt库
Linux下提示"libQt5Gui.so.5: cannot open"	动态库路径未配置	使用linuxdeploy重新打包或设置LD_LIBRARY_PATH
macOS提示"无法打开因为无法验证开发者"	应用未签名	右键打开或使用xattr -d com.apple.quarantine QtScrcpy.app

5.2 功能异常问题

💡 常见问题修复：

1. 截图功能失效：确保保留qjpeg.dll（Windows）或相应的Qt图像插件
2. ADB无法连接：检查adb.exe是否在应用目录且具有执行权限
3. 配置无法保存：验证config目录是否具有写入权限（chmod 755 config）

5.3 性能优化

• 启动速度慢：删除不必要的插件和翻译文件
• 高内存占用：在配置文件中降低视频分辨率（config.ini中设置max_size=720）
• 卡顿问题：关闭不必要的后台进程，确保设备USB连接稳定

总结

通过本文介绍的5个步骤，你已掌握QtScrcpy绿色版的跨平台制作方法。核心在于理解各平台依赖处理机制，善用项目提供的CI脚本，并针对不同系统特性进行优化。绿色版不仅提升了软件的便携性，也为用户提供了一致的使用体验。

官方文档：docs/FAQ.md 打包脚本目录：ci/ 配置文件模板：config/config.ini