强曰为道

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

第 3 章：基本操作

第 3 章：基本操作

本章目标：掌握 Flatpak 的日常使用命令，包括安装、运行、更新、卸载等操作。

3.1 命令概览

Flatpak 的 CLI 工具结构清晰，主要命令分类如下：

类别命令说明
信息查询search, info, list, remotes搜索、查看详情、列出已装、仓库管理
生命周期install, update, uninstall安装、更新、卸载
运行控制run, enter, kill运行应用、进入沙箱、终止应用
权限管理override, permission-*权限覆盖、权限查看
仓库管理remote-add, remote-modify, remote-delete添加、修改、删除远程仓库
维护repair, unused-list, uninstall --unused修复、清理

3.2 搜索应用

# 按关键词搜索
flatpak search video player

# 输出示例：
# Name                      Description                                     Application ID                       Version    Branch Remotes
# VLC media player          VLC is a free and open source...                org.videolan.VLC                     3.0.21     stable flathub
# GNOME Videos              Play movies and videos                          org.gnome.Totem                      43.0       stable flathub
# Celluloid                 Simple GTK+ frontend for mpv                    io.github.celluloid_player.Celluloid  0.27       stable flathub

# 搜索特定应用
flatpak search gimp
flatpak search org.gimp.GIMP

# 从指定仓库搜索
flatpak search --user kde

# 列出仓库中所有应用
flatpak remote-ls flathub | wc -l  # 查看 Flathub 上的应用总数

💡 技巧：也可以在浏览器中访问 flathub.org 进行搜索，获得更丰富的展示。

3.3 安装应用

3.3.1 基本安装

# 从 Flathub 安装（系统级，需要 sudo）
sudo flatpak install flathub org.gimp.GIMP

# 用户级安装（推荐，无需 sudo）
flatpak install --user flathub org.gimp.GIMP

# 安装时指定分支（版本）
flatpak install flathub org.gimp.GIMP//stable

# 非交互式安装（CI/CD 场景）
flatpak install -y --noninteractive flathub org.gimp.GIMP

# 从 .flatpakref 文件安装
flatpak install https://flathub.org/repo/appstream/org.gimp.GIMP.flatpakref

# 从本地 .flatpak 文件安装
flatpak install org.gimp.GIMP.flatpak

3.3.2 安装过程详解

安装一个应用时，Flatpak 会自动处理以下步骤：

1. 解析应用 ID → 从远程仓库获取元数据
2. 检查依赖 → 确定需要的运行时和 SDK
3. 下载运行时 → 如果缺少运行时，自动下载
4. 下载应用 → 下载应用本身
5. 部署 → 部署到本地存储
6. 注册 → 注册 .desktop 文件和图标

3.3.3 处理依赖冲突

# 如果安装时提示缺少运行时
flatpak install flathub org.gnome.Calculator
# Error: runtime org.gnome.Platform version 47 not installed

# 手动安装运行时
flatpak install flathub org.gnome.Platform//47 org.gnome.Sdk//47

# 然后重新安装应用
flatpak install flathub org.gnome.Calculator

3.4 运行应用

3.4.1 基本运行

# 通过应用 ID 运行
flatpak run org.gimp.GIMP

# 传递参数给应用
flatpak run org.gimp.GIMP /path/to/image.png

# 以特定环境变量运行
flatpak run --env=GTK_DEBUG=interactive org.gimp.GIMP

# 禁用网络运行（测试网络依赖）
flatpak run --unshare=network org.gimp.GIMP

# 查看详细运行日志
flatpak run --verbose org.gimp.GIMP 2>&1 | tee /tmp/gimp-flatpak.log

3.4.2 沙箱内运行命令

# 在应用沙箱中运行 bash
flatpak run --command=bash org.gimp.GIMP

# 在沙箱中运行特定命令
flatpak run --command=ls org.gimp.GIMP /app/

# 查看沙箱中的环境变量
flatpak run --command=env org.gimp.GIMP

# 查看沙箱中的文件系统
flatpak run --command=cat org.gimp.GIMP /etc/os-release

3.4.3 管理运行中的应用

# 查看正在运行的 Flatpak 应用
flatpak ps

# 输出示例：
# Instance   PID    Application            Runtime
# abc123     12345  org.gimp.GIMP          org.gnome.Platform

# 进入正在运行的应用沙箱
flatpak enter abc123 bash
# 或使用 PID
flatpak enter 12345 bash

# 终止正在运行的应用
flatpak kill org.gimp.GIMP

3.5 更新应用

3.5.1 更新命令

# 更新所有应用和运行时
flatpak update

# 只更新某个应用
flatpak update org.gimp.GIMP

# 更新运行时
flatpak update --runtime

# 用户级更新
flatpak update --user

# 查看可用更新（不实际更新）
flatpak update --appstream  # 先更新应用元数据
flatpak remote-ls --updates  # 列出有更新的应用

# 非交互式更新（CI/CD 场景）
flatpak update -y --noninteractive

3.5.2 更新策略

# 查看应用当前版本
flatpak info org.gimp.GIMP | grep Version

# 查看远程仓库中最新版本
flatpak remote-info flathub org.gimp.GIMP | grep Version

# 切换到 beta 分支
flatpak update --commit=beta org.gimp.GIMP  # 不推荐，应使用 remote 分支

# 配置自动更新（通过 systemd timer）
# Flatpak 本身不提供自动更新，但 GNOME Software / KDE Discover 会自动检查

3.6 卸载应用

# 卸载应用
flatpak uninstall org.gimp.GIMP

# 非交互式卸载
flatpak uninstall -y --noninteractive org.gimp.GIMP

# 卸载并删除应用数据（谨慎！）
rm -rf ~/.var/app/org.gimp.GIMP/

# 清理不再使用的运行时
flatpak uninstall --unused

# 查看即将被清理的内容
flatpak unused

# 卸载所有用户级应用
flatpak uninstall --user --all  # 危险操作，确认后再执行

3.7 列出与查看信息

3.7.1 列出已安装内容

# 列出所有已安装的应用
flatpak list --app

# 列出所有已安装的运行时
flatpak list --runtime

# 自定义列显示
flatpak list --app --columns=application,version,size

# 以 JSON 格式输出（方便脚本处理）
flatpak list --app --columns=application --show-details

# 只显示应用 ID
flatpak list --app --columns=application

3.7.2 查看应用详情

# 查看应用完整信息
flatpak info org.gimp.GIMP

# 输出示例：
# GIMP - Create images and edit photographs
#         Application ID: org.gimp.GIMP
#                Version: 2.10.38
#                   Arch: x86_64
#                  Branch: stable
#            Collection: org.flathub.Stable
#                  Origin: flathub
#          Installation: user
#            Installed: 194.5 MB
#              Runtime: org.gnome.Platform/x86_64/47
#                 Sdk: org.gnome.Sdk/x86_64/47
#              Commit: abc123def456...
#           GPG: RSA/SHA256, ...
#         Subject: ...
#            Date: 2026-04-15

# 查看应用的权限
flatpak info --show-permissions org.gimp.GIMP

# 查看应用的元数据
flatpak info --show-metadata org.gimp.GIMP

# 查看应用的文件系统路径
flatpak info --show-location org.gimp.GIMP

3.7.3 查看仓库信息

# 列出所有远程仓库
flatpak remotes

# 详细仓库信息
flatpak remote-info flathub

# 列出仓库中的所有应用（只显示 ID）
flatpak remote-ls flathub --columns=application | head -20

# 列出仓库中有更新的应用
flatpak remote-ls --updates

3.8 配置管理

3.8.1 Flatpak 全局配置

# 查看当前配置
flatpak config

# 设置默认安装位置为用户级
flatpak config --set default-system-flatpak-user-installations "user"

# 设置语言（影响应用界面语言）
flatpak config --set-languages "zh_CN en_US"

# 设置额外语言
flatpak config --set-languages "zh_CN" --add-languages "en_US"

# 配置 HTTP 代理
flatpak config --set http-proxy "http://proxy.example.com:8080"

# 配置 SOCKS 代理
flatpak config --set socks-proxy "socks5://proxy.example.com:1080"

3.8.2 仓库配置

# 修改仓库 URL
flatpak remote-modify flathub --url=https://dl.flathub.org/repo/flathub.flatpakrepo

# 禁用仓库（不删除，只暂停使用）
flatpak remote-modify flathub --disable

# 启用仓库
flatpak remote-modify flathub --enable

# 设置仓库为用户级
flatpak remote-modify flathub --user

# 删除仓库
flatpak remote-delete flathub

# 导入 GPG 密钥
flatpak remote-modify --gpg-import=/path/to/key.gpg my-repo

3.9 修复与维护

# 修复 flatpak 安装（检查并修复损坏的文件）
flatpak repair

# 修复用户级安装
flatpak repair --user

# 修复特定仓库
flatpak repair --repo=flathub

# 删除不再使用的运行时和扩展
flatpak uninstall --unused

# 查看磁盘使用情况
flatpak list --app --columns=application,size | sort -k2 -h

# 清理临时文件
rm -rf ~/.local/share/flatpak/.ref  # 通常不需要手动清理

3.10 批量操作脚本

3.10.1 批量安装脚本

#!/bin/bash
# batch-install.sh - 批量安装常用 Flatpak 应用

set -e

# 应用列表
APPS=(
    "org.gimp.GIMP"
    "org.inkscape.Inkscape"
    "org.videolan.VLC"
    "org.libreoffice.LibreOffice"
    "com.visualstudio.code"
    "org.mozilla.firefox"
    "org.gnome.Calculator"
    "org.gnome.TextEditor"
)

echo "开始安装 ${#APPS[@]} 个 Flatpak 应用..."

for app in "${APPS[@]}"; do
    echo "正在安装: $app"
    flatpak install -y --noninteractive flathub "$app" || {
        echo "警告: 安装 $app 失败，跳过"
        continue
    }
    echo "✓ $app 安装完成"
done

echo "所有安装完成！"
flatpak list --app --columns=application,version

3.10.2 批量更新脚本

#!/bin/bash
# batch-update.sh - 更新所有 Flatpak 应用并报告

echo "=== Flatpak 更新检查 ==="
echo "时间: $(date)"
echo ""

# 更新应用元数据
flatpak update --appstream -y --noninteractive 2>/dev/null

# 列出有更新的应用
echo "可用更新:"
flatpak remote-ls --updates 2>/dev/null || echo "无法获取更新列表"

echo ""
echo "正在执行更新..."
flatpak update -y --noninteractive

echo ""
echo "更新后状态:"
flatpak list --app --columns=application,version
echo ""

# 清理未使用的运行时
echo "清理未使用的运行时..."
flatpak uninstall --unused -y --noninteractive 2>/dev/null || echo "无需清理"
echo "=== 更新完成 ==="

3.11 业务场景

场景 1：新机器环境快速配置

新员工入职，需要快速配置 Linux 工作站的开发环境：

#!/bin/bash
# onboarding-flatpak.sh

# 1. 确保 Flathub 已配置
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

# 2. 安装开发工具
flatpak install -y flathub \
    com.visualstudio.code \
    org.gnome.Builder \
    org.gimp.GIMP

# 3. 安装办公工具
flatpak install -y flathub \
    org.libreoffice.LibreOffice \
    org.mozilla.firefox \
    org.telegram.desktop

echo "开发环境配置完成！"

场景 2：应用回滚

某次更新导致应用不稳定，需要回滚到之前的版本：

# 查看应用的提交历史
flatpak info --show-commit org.gimp.GIMP

# 回滚到之前的版本（OSTree 级别操作）
CURRENT_COMMIT=$(flatpak info --show-commit org.gimp.GIMP)
echo "当前版本: $CURRENT_COMMIT"

# 注意：Flatpak 没有直接的 rollback 命令
# 方案 1：使用 Flathub Beta 仓库中的旧版本
# 方案 2：从本地备份的 .flatpak 文件安装
# 方案 3：使用 ostree 直接管理版本

3.12 注意事项

⚠️ 应用数据不会自动删除
flatpak uninstall 只删除应用文件，不会删除 ~/.var/app/<app-id>/ 下的用户数据。如需完全清理，需手动删除该目录。

⚠️ 更新可能导致兼容性问题
大版本更新（如 GNOME 46 → 47）可能引入 API 变化。生产环境中建议先在测试环境验证更新。

⚠️ flatpak repair 可能耗时较长
该命令会校验所有已安装包的完整性，在有大量应用时可能需要几分钟。

⚠️ 国内网络问题
Flathub 下载速度可能较慢，建议配置镜像源或使用代理。

3.13 扩展阅读