3步打造专业级Debian包：wiliwili手柄客户端Linux部署指南

wiliwili是专为手柄控制设计的跨平台B站客户端，支持多设备运行。本文将详细介绍wiliwili Linux打包的全流程，帮助开发者和用户轻松制作并部署专业的Debian软件包。

核心价值：为何选择Debian包部署wiliwili

Debian软件包（.deb）是Linux系统中广泛使用的软件分发格式，采用该方式部署wiliwili手柄客户端具有显著优势：

• 简化安装流程：用户只需通过dpkg -i命令即可完成安装，无需手动配置依赖和环境变量
• 标准化管理：与系统包管理器深度集成，支持版本控制、升级和卸载操作
• 跨发行版兼容：适用于Debian、Ubuntu及其衍生系统，覆盖广泛用户群体
• 手柄优化保障：确保客户端在Linux环境下保持对手柄控制的原生支持

图1：wiliwili客户端在Linux系统中的运行界面，展示了手柄优化的用户界面设计

环境配置：构建专业打包环境

基础依赖安装

首先安装打包所需的核心工具链：

# 安装Debian打包工具集
sudo apt update && sudo apt install -y \
  build-essential \        # 基础编译工具
  dpkg-dev \               # Debian包开发工具
  dh-make \                # Debian化工具
  libmpv-dev \             # 媒体播放依赖
  libsdl2-dev              # 手柄输入支持库

预期结果：所有依赖包成功安装，无错误提示。可通过dpkg -l dpkg-dev验证核心工具是否安装。

源码准备

获取wiliwili项目源码：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/wi/wiliwili
cd wiliwili

预期结果：项目源码成功下载到本地，当前目录切换至项目根目录。

模块化实施：双路径打包方案

基础版：3步快速打包

第1步：编译应用程序

# 创建并进入构建目录
mkdir -p build && cd build

# 生成Makefile（启用桌面平台支持）
cmake .. -DPLATFORM_DESKTOP=ON -DCMAKE_BUILD_TYPE=Release

# 并行编译（使用所有CPU核心）
make -j$(nproc)

参数说明：

• -DPLATFORM_DESKTOP=ON：指定构建桌面平台版本
• -DCMAKE_BUILD_TYPE=Release：启用发布模式优化
• -j$(nproc)：根据CPU核心数并行编译

预期结果：在build目录下生成wiliwili可执行文件，无编译错误。

第2步：准备打包资源

# 生成多分辨率图标
cd scripts/linux
chmod +x gen_icons.sh
./gen_icons.sh

# 返回项目根目录
cd ../../

预期结果：在scripts/linux/icons目录下生成16x16、24x24、32x32等多种尺寸的图标文件。

第3步：构建Debian包

# 创建打包工作目录
mkdir -p wiliwili-deb/DEBIAN wiliwili-deb/usr/bin wiliwili-deb/usr/share/applications wiliwili-deb/usr/share/icons/hicolor

# 复制可执行文件
cp build/wiliwili wiliwili-deb/usr/bin/

# 复制桌面文件
cp scripts/linux/cn.xfangfang.wiliwili.desktop wiliwili-deb/usr/share/applications/

# 复制图标文件
find scripts/linux/icons -name "*.png" -exec cp {} wiliwili-deb/usr/share/icons/hicolor/{} \;

# 创建控制文件
cat > wiliwili-deb/DEBIAN/control << EOF
Section: video
Priority: optional
Maintainer: Your Name <[e-mail]>
Version: 1.0.0-1
Homepage: https://example.com/wiliwili
Package: wiliwili
Architecture: amd64
Depends: libass9, libdbus-1-3, libx11-6, libv4l-0, libpulse0, libuchardet0, libwebp6, libssl1.1
Description: A third-party Bilibili client designed specifically for controller users
EOF

# 构建Debian包
dpkg-deb --build wiliwili-deb

预期结果：在当前目录生成wiliwili-deb.deb文件，文件大小约5-10MB。

进阶版：深度定制打包流程

定制控制文件

创建高级控制文件wiliwili-deb/DEBIAN/control，添加更多元数据：

Section: video
Priority: optional
Maintainer: Your Name <[e-mail]>
Version: 1.0.0-1
Homepage: https://example.com/wiliwili
Package: wiliwili
Architecture: amd64
Depends: libass9 (>= 0.14.0), libdbus-1-3 (>= 1.12.2), libx11-6, libv4l-0, libpulse0, libuchardet0, libwebp6, libssl1.1
Recommends: joystick, xboxdrv
Suggests: mpv-mpris, gnome-shell-extension-appindicator
Description: A third-party Bilibili client designed specifically for controller users
 Wiliwili is a cross-platform Bilibili client optimized for game controllers.
 It supports video playback, live streaming, and interactive features with
 dedicated controller mappings for an enhanced viewing experience.

关键参数说明：

• Depends：核心依赖项，指定最低版本要求
• Recommends：推荐安装的辅助包
• Suggests：可选增强功能包

添加安装后脚本

创建wiliwili-deb/DEBIAN/postinst文件：

#!/bin/bash
set -e

# 更新图标缓存
update-icon-caches /usr/share/icons/hicolor/*

# 更新桌面数据库
update-desktop-database /usr/share/applications

# 显示安装完成信息
echo "wiliwili has been installed successfully!"
echo "You can launch it from your application menu or run 'wiliwili' in terminal."

exit 0

添加执行权限：

chmod +x wiliwili-deb/DEBIAN/postinst

预期结果：软件包安装后自动更新系统图标缓存和桌面数据库。

跨架构适配对照表

架构	编译参数	控制文件修改	测试环境
amd64	-DCMAKE_BUILD_TYPE=Release	Architecture: amd64	Ubuntu 20.04+
arm64	-DCMAKE_BUILD_TYPE=Release -DARCH=arm64	Architecture: arm64	Debian 11 (ARM)
i386	-DCMAKE_BUILD_TYPE=Release -DARCH=i386	Architecture: i386	Ubuntu 18.04 i386
armhf	-DCMAKE_BUILD_TYPE=Release -DARCH=armhf	Architecture: armhf	Raspbian 10

自动化打包脚本模板

创建build_deb.sh自动化脚本：

#!/bin/bash
set -e

# 配置参数
VERSION="1.0.0"
ARCH="amd64"
MAINTAINER="Your Name <[e-mail]>"
OUTPUT_DIR="build/packages"

# 创建输出目录
mkdir -p $OUTPUT_DIR

# 编译应用
echo "🔍 开始编译应用程序..."
mkdir -p build && cd build
cmake .. -DPLATFORM_DESKTOP=ON -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
cd ..

# 准备打包结构
echo "🔍 准备打包文件结构..."
PKG_DIR="wiliwili_${VERSION}_${ARCH}"
rm -rf $PKG_DIR
mkdir -p $PKG_DIR/DEBIAN $PKG_DIR/usr/bin $PKG_DIR/usr/share/applications $PKG_DIR/usr/share/icons/hicolor

# 复制文件
cp build/wiliwili $PKG_DIR/usr/bin/
cp scripts/linux/cn.xfangfang.wiliwili.desktop $PKG_DIR/usr/share/applications/
find scripts/linux/icons -name "*.png" -exec cp {} $PKG_DIR/usr/share/icons/hicolor/{} \;

# 生成控制文件
echo "🔍 生成控制文件..."
cat > $PKG_DIR/DEBIAN/control << EOF
Section: video
Priority: optional
Maintainer: $MAINTAINER
Version: $VERSION-1
Homepage: https://example.com/wiliwili
Package: wiliwili
Architecture: $ARCH
Depends: libass9, libdbus-1-3, libx11-6, libv4l-0, libpulse0, libuchardet0, libwebp6, libssl1.1
Description: A third-party Bilibili client designed specifically for controller users
EOF

# 添加postinst脚本
cat > $PKG_DIR/DEBIAN/postinst << "EOF"
#!/bin/bash
set -e
update-icon-caches /usr/share/icons/hicolor/*
update-desktop-database /usr/share/applications
echo "wiliwili has been installed successfully!"
exit 0
EOF
chmod +x $PKG_DIR/DEBIAN/postinst

# 构建deb包
echo "🔍 构建Debian软件包..."
dpkg-deb --build $PKG_DIR
mv ${PKG_DIR}.deb $OUTPUT_DIR/

echo "📌 打包完成：$OUTPUT_DIR/${PKG_DIR}.deb"

添加执行权限并运行：

chmod +x build_deb.sh
./build_deb.sh

预期结果：在build/packages目录下生成命名格式为wiliwili_版本_架构.deb的软件包。

问题诊断：常见问题速查表

症状	可能原因	解决方案
编译错误：libmpv not found	未安装libmpv开发库	sudo apt install libmpv-dev
运行时提示缺少共享库	依赖项未正确安装	sudo apt -f install 自动修复依赖
图标不显示	图标缓存未更新	update-icon-caches /usr/share/icons/hicolor/*
手柄无响应	SDL2库未安装	sudo apt install libsdl2-dev 重新编译
打包错误：权限被拒绝	临时目录权限不足	sudo chown -R $USER:$USER wiliwili-deb

⚠️ 危险操作警告：执行sudo make install可能会覆盖系统文件。建议使用Debian包管理系统进行安装，如需手动测试，可使用make DESTDIR=./test install进行隔离安装。

扩展优化：提升打包质量与兼容性

依赖版本控制

为确保兼容性，建议在控制文件中指定依赖项的最低版本：

Depends: libass9 (>= 0.14.0), libdbus-1-3 (>= 1.12.2), libx11-6 (>= 2:1.6.7)

多架构构建

使用Docker实现多架构打包：

# 构建arm64架构包
docker run --rm -v $(pwd):/work -w /work multiarch/debian-debootstrap:arm64-buster ./build_deb.sh

测试自动化

添加自动化测试步骤到打包流程：

# 在build_deb.sh中添加
echo "🔍 运行自动化测试..."
./build/wiliwili --test-mode
if [ $? -ne 0 ]; then
  echo "❌ 测试失败，中止打包"
  exit 1
fi

打包质量检查清单

1. [ ] 软件包能在目标系统上正常安装和卸载
2. [ ] 可执行文件位于/usr/bin目录下
3. [ ] 桌面文件正确安装并出现在应用菜单中
4. [ ] 所有图标尺寸都已正确安装
5. [ ] 安装后能通过命令wiliwili启动
6. [ ] 手柄控制功能正常工作
7. [ ] 视频播放和音频输出正常
8. [ ] 软件包大小控制在合理范围内（建议<20MB）
9. [ ] 控制文件中的依赖关系完整准确
10. [ ] 在至少两个不同版本的Debian/Ubuntu系统上测试通过

通过遵循本指南，您可以构建出专业级的wiliwili Debian包，为Linux用户提供流畅的手柄客户端体验。wiliwili Linux打包不仅简化了安装流程，还确保了应用在各种Linux发行版上的一致性和可靠性，是手柄用户享受B站内容的理想选择。