WPEWebKit在Ubuntu 18.04上的编译配置与常见问题解决

1. 环境准备与依赖安装

在Ubuntu 18.04上编译WPEWebKit确实是个技术活，这个老系统和新引擎的组合就像让传统燃油车跑新能源系统，需要解决不少兼容性问题。我去年在嵌入式设备上部署WPEWebKit时，花了整整三天时间才搞定所有依赖，这里把踩过的坑都总结给你。

首先得把系统基础环境搭好。Ubuntu 18.04默认的软件源太旧，很多新库都没有，建议先更新源：

sudo apt update && sudo apt upgrade -y sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo apt install software-properties-common

核心依赖包要分批次安装，我习惯把它们分成三类：

1. 编译工具链：gcc-8、g++-8（必须用8版本，太高会出问题）、cmake、ninja-build、meson
2. 基础库：libglib2.0-dev、libsoup2.4-dev、libsqlite3-dev、libjpeg-dev
3. 多媒体支持：gstreamer1.0-plugins-base、gstreamer1.0-plugins-good、libgstreamer1.0-dev

实际安装命令这样写更稳妥：

sudo apt install -y \ gcc-8 g++-8 \ cmake ninja-build meson \ libglib2.0-dev libsoup2.4-dev \ libgstreamer1.0-dev \ libwayland-dev xorg-dev \ libxt-dev libwoff2-dev \ libopenjp2-7-dev \ libsecret-1-dev

有个特别容易忽略的点是GStreamer的版本。Ubuntu 18.04默认安装的是1.14版本，但WPEWebKit 2.32+需要至少1.16的特性。我建议手动编译安装GStreamer 1.18：

wget https://gstreamer.freedesktop.org/src/gstreamer/gstreamer-1.18.6.tar.xz tar -xf gstreamer-1.18.6.tar.xz cd gstreamer-1.18.6 meson build --prefix=/usr/local ninja -C build sudo ninja -C build install

2. 源码获取与目录结构

WPEWebKit的编译需要四个核心组件协同工作，就像搭积木一样缺一不可。我建议在用户目录下创建专门的工作空间：

mkdir -p ~/wpe/{source,inst} cd ~/wpe/source

组件下载有讲究，不是越新越好。经过多次测试，这个组合最稳定：

• libwpe-1.10.0.tar.xz
• wpebackend-fdo-1.6.0.tar.xz
• wpewebkit-2.32.0.tar.xz
• cog-0.5.1.tar.xz

下载后解压要注意保留版本号后缀，方便后续管理：

for pkg in *.tar.xz; do tar -xf "$pkg"; done

目录结构最终应该是这样的：

~/wpe ├── source │ ├── libwpe-1.10.0 │ ├── wpebackend-fdo-1.6.0 │ ├── wpewebkit-2.32.0 │ └── cog-0.5.1 └── inst ├── bin ├── lib └── include

3. 分步编译指南

3.1 libwpe编译

libwpe是基础图形抽象层，相当于WebKit的地基。编译时要注意三点：

1. 必须指定Debug模式方便排错
2. 安装路径要统一
3. 生成编译命令数据库

具体操作：

cd libwpe-1.10.0 mkdir build && cd build cmake .. \ -DCMAKE_EXPORT_COMPILE_COMMANDS=YES \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_INSTALL_PREFIX=~/wpe/inst make -j$(nproc) make install

验证是否成功：

ls ~/wpe/inst/lib/libwpe-1.0.so

3.2 wpebackend-fdo编译

这个后端负责与显示系统交互，需要特别注意Wayland协议：

cd wpebackend-fdo-1.6.0 mkdir build && cd build cmake .. \ -DCMAKE_INSTALL_PREFIX=~/wpe/inst \ -DCMAKE_PREFIX_PATH=~/wpe/inst make -j$(nproc) make install

常见问题是找不到wayland-protocols，解决方法：

wget http://archive.ubuntu.com/ubuntu/pool/main/w/wayland-protocols/wayland-protocols_1.20-1_all.deb sudo dpkg -i wayland-protocols_1.20-1_all.deb

3.3 WPEWebKit编译

这是最复杂的部分，关键是要处理C++版本兼容问题。我的配置方案：

cd wpewebkit-2.32.0 ./Tools/wpe/install-dependencies mkdir build && cd build cmake .. \ -GNinja \ -DPORT=WPE \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_INSTALL_PREFIX=~/wpe/inst \ -DCMAKE_CXX_FLAGS="-fpermissive" \ -DENABLE_MINIBROWSER=ON \ -DUSE_WPE_BACKEND_FDO=1.6 \ -DWPE_INCLUDE_DIR=~/wpe/inst/include/wpe-1.0 \ -DUSE_SOUP2=ON

几个关键参数说明：

• -fpermissive：放宽C++标准检查
• -USE_SOUP2=ON：强制使用libsoup2
• -GNinja：使用更快的ninja构建系统

编译命令：

ninja -j$(nproc) ninja install

4. 常见问题解决方案

4.1 GStreamer API不兼容

典型错误：

error: braces around scalar initializer for type 'gboolean (*)(GstAppSink*, gpointer)'

这是因为GStreamer 1.18+新增了事件回调接口。修改方法：

1. 找到报错文件（通常是ImageDecoderGStreamer.cpp）
2. 在GstAppSinkCallbacks结构体末尾添加nullptr：

static GstAppSinkCallbacks callbacks = { nullptr, [](GstAppSink* sink, gpointer userData) -> GstFlowReturn { return static_cast<AudioSourceProviderGStreamer*>(userData)->handleSample(sink, true); }, [](GstAppSink* sink, gpointer userData) -> GstFlowReturn { return static_cast<AudioSourceProviderGStreamer*>(userData)->handleSample(sink, false); }, nullptr, // 新增的事件回调 { nullptr } };

4.2 C++11标准冲突

遇到constexpr相关错误时，修改Internals.cpp：

constexpr TreeType convertType(Internals::TreeType type) { switch (type) { case Internals::Tree: return Tree; case Internals::ShadowIncludingTree: return ShadowIncludingTree; case Internals::ComposedTree: return ComposedTree; } return Tree; // 移除ASSERT_NOT_REACHED() }

4.3 Wayland协议缺失

当出现text-input-unstable-v3错误时：

wget http://archive.ubuntu.com/ubuntu/pool/main/w/wayland-protocols/wayland-protocols_1.20-1_all.deb sudo dpkg -i wayland-protocols_1.20-1_all.deb

5. 运行与调试

5.1 环境变量配置

在~/.bashrc中添加：

export PATH=$PATH:~/wpe/inst/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/wpe/inst/lib export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:~/wpe/inst/lib/pkgconfig

5.2 启动Weston合成器

新建终端执行：

weston --socket=wpe --width=1280 --height=720

在新启动的Weston终端中运行：

export LD_LIBRARY_PATH=~/wpe/inst/lib cog --platform=fdo https://www.baidu.com

5.3 X11模式运行

如果需要X11支持，需要编译cog 0.10.0：

cmake .. \ -DCMAKE_BUILD_TYPE=Debug \ -DCMAKE_INSTALL_PREFIX=~/wpe/inst \ -DCOG_PLATFORM_X11=ON \ -GNinja

运行时指定平台：

cog --platform=x11 https://example.com

5.4 调试技巧

启用详细日志：

export GST_DEBUG="3,webkit*:7" export WEBKIT_FORCE_SANDBOX=0 cog --platform=fdo https://example.com

如果遇到段错误，用gdb调试：

gdb --args cog --platform=fdo https://example.com (gdb) r (gdb) bt full