强曰为道

与天地相似，故不违。知周乎万物，而道济天下，故不过。旁行而不流，乐天知命，故不忧.
文档目录

第 8 章：扩展机制

第 8 章：扩展机制

本章目标：理解 Flatpak 扩展 (Extension) 机制，学会使用主题/字体/编解码器扩展，并能创建自定义扩展。

8.1 扩展概述

8.1.1 什么是扩展

扩展 (Extension) 是 Flatpak 的可选组件系统，用于向运行时或应用添加额外的功能，而无需修改基础运行时本身。

┌──────────────────────────────────────────────────┐
│                 Flatpak 应用                      │
├──────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐   │
│  │ GTK 主题  │  │ 字体扩展  │  │ H.264 编解码 │   │
│  │ 扩展     │  │          │  │ 器扩展        │   │
│  └──────────┘  └──────────┘  └──────────────┘   │
├──────────────────────────────────────────────────┤
│              基础运行时 (Runtime)                 │
└──────────────────────────────────────────────────┘

8.1.2 扩展的类型

扩展类型说明安装级别
运行时扩展随运行时自动挂载系统级
应用扩展特定应用的可选组件应用级
共享扩展多个应用共享的组件系统级

8.2 常用扩展

8.2.1 GTK 主题扩展

GTK 主题扩展让 Flatpak 应用能跟随系统主题。

# 查看可用的 GTK3 主题扩展
flatpak search gtk3theme

# 安装常用的 GTK 主题
flatpak install flathub org.gtk.Gtk3theme.Adwaita-dark
flatpak install flathub org.gtk.Gtk3theme.Adwaita-light

# 安装第三方主题（以 Dracula 为例）
flatpak install flathub org.gtk.Gtk3theme.Dracula

# 安装 Breeze 主题（KDE 默认）
flatpak install flathub org.gtk.Gtk3theme.Breeze

# 查看已安装的主题扩展
flatpak list --runtime | grep -i theme

主题扩展工作原理：

1. 运行时定义了扩展点 (extension-point)
2. 应用启动时，Flatpak 自动检测已安装的主题扩展
3. 将主题文件挂载到应用沙箱的 /usr/share/themes/ 目录
4. 应用通过 GTK 主题引擎自动应用主题

8.2.2 字体扩展

# 安装额外字体
flatpak install flathub org.freedesktop.Platform.Extension.openh264//24.08

# 查看可用字体扩展
flatpak remote-ls flathub | grep -i font

# 手动安装字体到 Flatpak 可访问的位置
# 方法 1：通过 XDG 数据目录
mkdir -p ~/.local/share/fonts
cp MyFont.ttf ~/.local/share/fonts/
fc-cache -fv

# 方法 2：使用 Flatpak 字体挂载
# Flatpak 自动挂载 ~/.local/share/fonts 到沙箱中

字体挂载路径：

宿主路径沙箱内路径
~/.local/share/fonts/run/host/user-fonts/
/usr/local/share/fonts/run/host/fonts/
/usr/share/fonts运行时内（已包含）

8.2.3 编解码器扩展

# 安装 OpenH264 编解码器（Cisco 提供，免费）
flatpak install flathub org.freedesktop.Platform.Extension.openh264//24.08

# 安装额外的 GStreamer 插件
# （通常已包含在运行时中，某些格式需要额外安装）

# 查看运行时中包含的编解码器
flatpak run --command=gst-inspect-1.0 org.freedesktop.Platform//24.08 | grep -i h264

编解码器支持情况：

编解码器状态说明
H.264✅ 通过 OpenH264 扩展Cisco 专利许可
H.265/HEVC⚠️ 受限专利问题，需额外处理
VP8/VP9✅ 内置开源，无专利问题
AV1✅ 内置开源，下一代标准
MP3✅ 内置通过 GStreamer 插件
AAC✅ 内置通过 FAAD
FLAC✅ 内置开源格式

8.2.4 Mesa 驱动扩展

# 查看 Mesa 驱动扩展
flatpak remote-ls flathub | grep -i mesa

# 32 位 Mesa 驱动（Wine/Steam 游戏需要）
flatpak install flathub org.freedesktop.Platform.Compat.i386//24.08
flatpak install flathub org.freedesktop.Platform.GL32.default//24.08

8.3 扩展的工作原理

8.3.1 扩展点 (Extension Point)

扩展点在运行时的元数据中定义：

# 运行时元数据中定义的扩展点示例
[Extension org.gtk.Gtk3theme.*]
directory=share/themes
subdirectories=true
no-autodownload=false
autodelete=true
merge-dirs=share/gtk-3.0/overrides;share/themes
字段说明
directory扩展在运行时中的挂载目录
subdirectories是否支持子目录（主题需要）
no-autodownload是否禁用自动下载
autodelete无应用使用时是否自动删除
merge-dirs需要合并的目录列表

8.3.2 扩展自动发现

# Flatpak 自动发现扩展的逻辑：
# 1. 检查运行时定义的扩展点
# 2. 在已配置的仓库中搜索匹配的扩展
# 3. 匹配 app-id 规则：org.gtk.Gtk3theme.<主题名>
# 4. 自动挂载到应用沙箱

# 查看某个运行时的扩展点
flatpak info --show-metadata org.freedesktop.Platform//24.08 | grep -A 10 Extension

8.4 创建自定义扩展

8.4.1 创建主题扩展

# 步骤 1：创建扩展目录结构
mkdir -p my-theme/org.gtk.Gtk3theme.MyTheme/current
mkdir -p my-theme/org.gtk.Gtk3theme.MyTheme/current/gtk-3.0

# 步骤 2：创建主题文件
cat > my-theme/org.gtk.Gtk3theme.MyTheme/current/gtk-3.0/gtk.css << 'EOF'
/* MyTheme GTK3 CSS */
@define-color bg_color #2b2b2b;
@define-color fg_color #ffffff;
@define-color base_color #333333;
@define-color text_color #e0e0e0;
@define-color selected_bg_color #4a90d9;
@define-color selected_fg_color #ffffff;

/* 应用自定义样式 */
window.background {
    background-color: @bg_color;
    color: @fg_color;
}

button {
    background-color: shade(@bg_color, 1.2);
    color: @fg_color;
    border: 1px solid shade(@bg_color, 0.8);
    border-radius: 4px;
    padding: 6px 12px;
}

button:hover {
    background-color: @selected_bg_color;
}
EOF

# 步骤 3：创建扩展 Manifest
cat > org.gtk.Gtk3theme.MyTheme.json << 'EOF'
{
    "id": "org.gtk.Gtk3theme.MyTheme",
    "branch": "1.0",
    "runtime": "org.gtk.Gtk3theme.MyTheme",
    "runtime-version": "1.0",
    "sdk": "org.gnome.Sdk//47",
    "build-extension": true,
    "separate-locales": false,
    "cleanup": [],
    "modules": [
        {
            "name": "my-theme",
            "buildsystem": "simple",
            "build-commands": [
                "mkdir -p /usr/share/themes/MyTheme/gtk-3.0",
                "cp -r gtk-3.0/gtk.css /usr/share/themes/MyTheme/gtk-3.0/"
            ],
            "sources": [
                {
                    "type": "dir",
                    "path": "my-theme/org.gtk.Gtk3theme.MyTheme/current"
                }
            ]
        }
    ]
}
EOF

# 步骤 4：构建扩展
flatpak-builder --force-clean --repo=theme-repo \
    theme-builddir org.gtk.Gtk3theme.MyTheme.json

# 步骤 5：添加仓库并安装
flatpak remote-add --no-gpg-verify my-themes theme-repo
flatpak install my-themes org.gtk.Gtk3theme.MyTheme

# 步骤 6：测试
# 系统主题设置为 MyTheme，然后运行 Flatpak 应用验证

8.4.2 创建编解码器扩展

{
    "id": "org.freedesktop.Platform.Extension.MyCodec",
    "branch": "24.08",
    "runtime": "org.freedesktop.Platform.Extension.MyCodec",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk//24.08",
    "build-extension": true,
    "separate-locales": false,
    "cleanup": [
        "*.a",
        "*.la"
    ],
    "modules": [
        {
            "name": "my-codec",
            "buildsystem": "autotools",
            "sources": [
                {
                    "type": "archive",
                    "url": "https://example.com/my-codec-1.0.tar.gz",
                    "sha256": "abc123..."
                }
            ],
            "post-install": [
                "mkdir -p /usr/lib/gstreamer-1.0",
                "cp /usr/lib/gstreamer-1.0/libgstmycodec.so /usr/lib/gstreamer-1.0/"
            ]
        }
    ]
}

8.4.3 创建应用扩展

{
    "app-id": "com.example.MyApp.Plugin",
    "branch": "stable",
    "runtime": "org.gnome.Platform",
    "runtime-version": "47",
    "sdk": "org.gnome.Sdk",
    "build-extension": true,
    "separate-locales": false,
    "modules": [
        {
            "name": "my-plugin",
            "buildsystem": "meson",
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/example/my-plugin.git",
                    "tag": "v1.0.0"
                }
            ]
        }
    ]
}

8.5 扩展管理

8.5.1 查看扩展

# 列出所有已安装的扩展
flatpak list --runtime | grep -i ext

# 查看运行时的扩展点
flatpak info --show-metadata org.freedesktop.Platform | grep -A 5 "\[Extension"

# 查看某个应用使用的扩展
flatpak info --show-permissions org.gimp.GIMP | grep extension

# 查看扩展详细信息
flatpak info org.freedesktop.Platform.Extension.openh264

8.5.2 扩展安装与卸载

# 安装扩展
flatpak install flathub org.freedesktop.Platform.Extension.openh264//24.08

# 卸载扩展
flatpak uninstall org.freedesktop.Platform.Extension.openh264

# 更新扩展
flatpak update org.freedesktop.Platform.Extension.openh264

# 禁用扩展（不卸载）
flatpak mask org.freedesktop.Platform.Extension.openh264

# 启用扩展
flatpak mask --remove org.freedesktop.Platform.Extension.openh264

8.5.3 扩展的挂载与合并

# 查看扩展在沙箱中的挂载点
flatpak run --command=ls org.gimp.GIMP /usr/share/themes/

# 查看扩展合并的目录
flatpak run --command=mount org.gimp.GIMP | grep -i theme

# 手动控制扩展挂载
# 在 Manifest 中：
# "finish-args": [
#     "--filesystem=xdg-config/gtk-3.0:ro"
# ]

8.6 扩展与权限

8.6.1 扩展权限继承

扩展通常继承其父运行时的权限，但可以添加额外的权限：

{
    "id": "org.freedesktop.Platform.Extension.MyCodec",
    "finish-args": [
        "--filesystem=xdg-videos:ro"
    ]
}

8.6.2 控制扩展访问

# 禁止某个应用使用特定扩展
# Flatpak 目前不支持直接禁止，但可以通过 override 限制

# 或者使用 mask 全局禁用扩展
flatpak mask org.gtk.Gtk3theme.SomeTheme

8.7 业务场景

场景 1：企业内部字体分发

企业需要为所有 Flatpak 应用提供统一的字体：

#!/bin/bash
# deploy-corporate-fonts.sh

FONT_NAME="CorporateSans"
FONT_VERSION="1.0"

# 创建字体扩展目录
mkdir -p fonts/org.freedesktop.Platform.Extension.${FONT_NAME}
cd fonts/org.freedesktop.Platform.Extension.${FONT_NAME}

# 创建字体文件
# (假设已准备好 .ttf 文件)
cp /path/to/CorporateSans-Regular.ttf .
cp /path/to/CorporateSans-Bold.ttf .

# 创建扩展 Manifest
cat > org.freedesktop.Platform.Extension.${FONT_NAME}.json << EOF
{
    "id": "org.freedesktop.Platform.Extension.${FONT_NAME}",
    "branch": "24.08",
    "runtime": "org.freedesktop.Platform.Extension.${FONT_NAME}",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk//24.08",
    "build-extension": true,
    "separate-locales": false,
    "cleanup": [],
    "modules": [
        {
            "name": "corporate-fonts",
            "buildsystem": "simple",
            "build-commands": [
                "install -Dm644 *.ttf /usr/share/fonts/truetype/corporate/"
            ],
            "sources": [
                {
                    "type": "dir",
                    "path": "."
                }
            ]
        }
    ]
}
EOF

# 构建扩展
flatpak-builder --force-clean --repo=font-repo \
    font-builddir org.freedesktop.Platform.Extension.${FONT_NAME}.json

# 分发给员工
echo "字体扩展已构建完成，仓库位于 font-repo/"
echo "员工可通过以下命令安装："
echo "flatpak remote-add --no-gpg-verify corp-fonts font-repo/"
echo "flatpak install corp-fonts org.freedesktop.Platform.Extension.${FONT_NAME}//24.08"

场景 2：游戏运行时扩展

为游戏提供额外的运行时组件（如 DirectX 兼容层）：

{
    "id": "org.freedesktop.Platform.Extension.GameCompat",
    "branch": "24.08",
    "runtime": "org.freedesktop.Platform.Extension.GameCompat",
    "runtime-version": "24.08",
    "sdk": "org.freedesktop.Sdk//24.08",
    "build-extension": true,
    "separate-locales": false,
    "modules": [
        {
            "name": "dxvk",
            "buildsystem": "meson",
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/doitsujin/dxvk.git",
                    "tag": "v2.3.1"
                }
            ]
        },
        {
            "name": "vkd3d-proton",
            "buildsystem": "meson",
            "sources": [
                {
                    "type": "git",
                    "url": "https://github.com/HansKristian-Work/vkd3d-proton.git",
                    "tag": "v2.11.1"
                }
            ]
        }
    ]
}

8.8 注意事项

⚠️ 扩展版本匹配
扩展的 runtime-version 必须与运行时版本匹配。GNOME 47 的运行时不能使用为 GNOME 46 构建的扩展。

⚠️ 主题扩展的局限性
GTK 主题扩展只影响 GTK3 应用。GTK4 应用使用 CSS，不支持传统的主题引擎。

⚠️ 专利编解码器
H.264 等受专利保护的编解码器可能在某些地区存在法律风险。OpenH264 由 Cisco 提供专利许可，但仅限于其 OpenH264 二进制形式。

⚠️ 扩展大小
某些扩展（如 32 位 Mesa 驱动）可能很大（~500 MB）。在磁盘空间有限的环境中谨慎安装。

8.9 扩展阅读