Intel® RealSense™ SDK在Ubuntu 22.04上的安装教程：从问题排查到性能优化

2026-04-09 09:46:58作者：秋泉律Samson

前言

在Ubuntu 22.04系统上安装Intel® RealSense™ SDK（软件开发工具包）时，用户常常会遇到各种挑战。无论是官方文档分散导致的安装步骤不连贯，还是内核版本兼容性问题引发的驱动编译失败，亦或是源码编译过程中缺失依赖库带来的晦涩错误提示，以及DKMS包与手动编译方案的选择困难，这些问题都可能让安装过程变得复杂。本安装教程将为您提供全面的安装指南，帮助您解决这些问题，顺利完成Intel® RealSense™ SDK的安装与配置，并进行性能优化。

一、痛点分析：三种典型用户的安装困境

1.1 开发者小王的源码编译挑战

小王是一名机器人视觉算法开发者，需要对RealSense SDK进行二次开发。他选择从源码编译安装，却在编译过程中遇到了诸多问题。首先是依赖库缺失，当他执行编译命令时，系统提示找不到openssl/opensslv.h文件，这让他陷入困惑，不知道该安装哪个具体的依赖包。经过一番搜索，他才发现需要安装libssl-dev。解决了依赖问题后，又出现了内核版本不匹配的情况，编译过程中频繁报错，提示某些内核函数不存在。小王不得不花费大量时间研究内核补丁，尝试各种补丁脚本，但由于对内核版本与补丁的对应关系不了解，多次尝试都以失败告终，严重影响了项目进度。

1.2 运维人员小李的DKMS包管理难题

小李负责公司多台Ubuntu 22.04工作站的RealSense设备部署。为了提高效率，他选择使用DKMS预编译包进行安装。然而，在安装过程中，他发现不同工作站的内核版本存在差异，有些工作站可以顺利安装DKMS包，而有些则提示内核版本不兼容。更麻烦的是，部分工作站在安装后出现了modprobe: ERROR: could not insert 'uvcvideo'错误，导致驱动无法加载。小李查看/var/lib/dkms/librealsense2-dkms日志，发现是由于内核更新后DKMS模块没有自动重新编译。他尝试重新安装DKMS包，但问题依旧存在，这让他对DKMS包的稳定性产生了怀疑。

1.3 普通用户小张的设备连接困扰

小张是一名 hobbyist，购买了RealSense相机用于3D建模。他按照网上的简单教程安装了RealSense SDK和Viewer工具，但启动Viewer后却发现无法显示图像。他检查了USB连接，确认相机已正确连接，但Viewer始终提示“Nothing is streaming! Toggle to start”。小张尝试更换USB端口，使用了电脑上的多个USB接口，包括USB 2.0和USB 3.0接口，但问题依然没有解决。他不知道是驱动安装问题还是相机硬件故障，感到十分无助。

二、创新分类体系：按用户角色选择安装方案

2.1 开发者方案：源码编译安装

对于需要进行二次开发、自定义功能或使用最新特性的开发者，源码编译安装是最佳选择。这种方式可以让开发者深入了解SDK的内部结构，根据自己的需求进行定制化开发。

2.2 运维人员方案：DKMS预编译包安装

运维人员通常需要在多台设备上快速部署RealSense SDK，DKMS预编译包安装方式可以大大提高部署效率。DKMS能够自动处理内核更新时的模块重新编译，确保驱动的持续可用性。

2.3 普通用户方案：简化安装脚本

普通用户更关注设备的快速使用，不需要进行复杂的配置和开发。简化安装脚本可以自动完成依赖安装、驱动配置等步骤，让用户轻松上手使用RealSense设备。

三、可视化决策树：选择适合您的安装方式

flowchart TD
    A[您是哪种用户角色?]
    A -->|开发者| B[需要自定义功能或最新特性吗?]
    A -->|运维人员| C[需要在多台设备快速部署吗?]
    A -->|普通用户| D[只需基本功能快速使用?]
    B -->|是| E[选择源码编译安装]
    B -->|否| F[选择DKMS预编译包安装]
    C -->|是| F
    C -->|否| E
    D --> G[选择简化安装脚本]

四、环境预检工具：一键检查系统兼容性

在开始安装Intel® RealSense™ SDK之前，建议先运行环境预检工具，检查系统是否满足安装要求。以下是一个简单的一键检查脚本：

#!/bin/bash

# 检查内核版本
kernel_version=$(uname -r)
echo "当前内核版本: $kernel_version"

# 检查USB端口
usb3_ports=$(lsusb | grep -i "3.0" | wc -l)
if [ $usb3_ports -eq 0 ]; then
    echo "警告: 未检测到USB 3.0端口，可能影响设备性能"
else
    echo "检测到USB 3.0端口，数量: $usb3_ports"
fi

# 检查依赖库
required_packages=("libssl-dev" "libusb-1.0-0-dev" "libudev-dev" "pkg-config" "libgtk-3-dev" "libglfw3-dev" "libgl1-mesa-dev" "libglu1-mesa-dev")
missing_packages=()
for pkg in "${required_packages[@]}"; do
    if ! dpkg -s $pkg >/dev/null 2>&1; then
        missing_packages+=($pkg)
    fi
done
if [ ${#missing_packages[@]} -ne 0 ]; then
    echo "缺少依赖库: ${missing_packages[*]}"
else
    echo "所有依赖库已安装"
fi

# 检查DKMS状态
if dpkg -s dkms >/dev/null 2>&1; then
    echo "DKMS已安装"
else
    echo "DKMS未安装"
fi

将以上脚本保存为check_environment.sh，然后执行以下命令运行：

chmod +x check_environment.sh
./check_environment.sh

预期结果

脚本将输出当前内核版本、USB 3.0端口检测情况、缺失的依赖库以及DKMS状态。根据输出结果，您可以提前解决系统中存在的问题，确保安装过程顺利进行。

风险提示

此脚本仅进行基本的环境检查，不能涵盖所有可能的问题。如果脚本提示缺少依赖库，请使用sudo apt-get install命令安装。对于内核版本不兼容的问题，您可能需要升级内核或选择其他安装方案。

五、分步操作卡片：三种安装方案的详细步骤

5.1 开发者方案：源码编译安装

步骤1：安装依赖项

# 安装基础编译工具
sudo apt-get install git cmake build-essential -y  # 安装git、cmake和基础编译工具，用于从源码构建项目

# 安装核心依赖库
sudo apt-get install libssl-dev libusb-1.0-0-dev libudev-dev \
pkg-config libgtk-3-dev libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev -y  # 安装SDK所需的各种依赖库，如SSL、USB、图形界面等相关库

预期结果：系统将自动下载并安装所需的依赖包，安装完成后没有错误提示。 风险提示：如果出现依赖冲突，可以尝试使用sudo apt-get -f install命令修复。

步骤2：源码获取与准备

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/li/librealsense.git  # 从指定仓库克隆librealsense源码
cd librealsense  # 进入源码目录

# 设置设备权限
sudo ./scripts/setup_udev_rules.sh  # 运行udev规则脚本，设置RealSense设备的访问权限

预期结果：仓库克隆成功，当前目录切换到librealsense，设备权限设置完成，没有错误提示。 风险提示：克隆仓库时如果网络不稳定，可能会导致克隆失败，需要重新执行克隆命令。

步骤3：内核补丁应用

# 适用于Ubuntu 22.04 HWE内核
sudo ./scripts/patch-realsense-ubuntu-lts-hwe.sh  # 执行针对Ubuntu 22.04 HWE内核的补丁脚本，解决内核兼容性问题

原理简述：为内核添加RealSense设备所需的特定驱动支持。 预期结果：补丁脚本执行完成，输出“补丁应用成功”等类似提示。 风险提示：补丁执行过程中可能会出现内核版本不匹配的错误，此时需要查看脚本日志/var/log/librealsense-setup.log，并根据日志提示解决问题。

步骤4：编译配置

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

# 基础配置（默认Debug模式）
cmake .. -DBUILD_EXAMPLES=true -DBUILD_GRAPHICAL_EXAMPLES=true  # 使用cmake生成Makefile，开启示例和图形化示例的构建

# 如需Release模式优化
# cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_EXAMPLES=true

预期结果：cmake配置成功，生成Makefile等编译所需文件，没有错误提示。 风险提示：如果配置过程中提示缺少依赖，需要回到步骤1安装相应的依赖库。

步骤5：编译与安装

# 使用多线程编译（N为CPU核心数）
make -j$(nproc)  # 使用所有可用CPU核心进行编译，加快编译速度

# 安装到系统目录
sudo make install  # 将编译好的库和可执行文件安装到系统目录

# 更新动态链接库缓存
sudo ldconfig  # 更新动态链接库缓存，使系统能够找到新安装的库

预期结果：编译过程顺利完成，没有错误提示，库文件和可执行文件成功安装到系统目录。 风险提示：编译过程中可能会出现内存不足的情况，如果您的系统内存较小，可以减少并行编译的线程数，如make -j2。

检查点：功能验证

# 运行深度采集示例
cd examples/capture
./rs-capture  # 运行深度采集示例程序

# 查看已安装组件版本
pkg-config --modversion librealsense2  # 输出已安装的librealsense2版本号，如2.54.1

预期结果：深度采集示例程序能够正常运行，显示相机采集的深度图像；版本号输出正确。

5.2 运维人员方案：DKMS预编译包安装

步骤1：环境准备

# 执行系统更新并安装HTTPS支持
sudo apt-get update && sudo apt-get upgrade -y  # 更新系统软件包到最新版本
sudo apt-get install apt-transport-https ca-certificates -y  # 安装HTTPS支持，以便访问HTTPS源

预期结果：系统更新完成，HTTPS支持安装成功。 风险提示：系统更新过程中可能会出现软件包冲突，需要根据提示进行处理。

步骤2：配置软件源

# 创建密钥存储目录
sudo mkdir -p /etc/apt/keyrings  # 创建存放APT密钥的目录

# 导入仓库公钥
curl -sSf https://librealsense.intel.com/Debian/librealsense.pgp | \
sudo tee /etc/apt/keyrings/librealsense.pgp > /dev/null  # 从指定URL下载并导入仓库公钥

# 添加官方仓库
echo "deb [signed-by=/etc/apt/keyrings/librealsense.pgp] https://librealsense.intel.com/Debian/apt-repo jammy main" | \
sudo tee /etc/apt/sources.list.d/librealsense.list  # 添加RealSense官方APT源

# 更新软件包索引
sudo apt-get update  # 更新软件包索引，使系统能够识别新添加的源

预期结果：密钥导入成功，软件源添加完成，软件包索引更新成功。 风险提示：如果导入密钥或添加源时出现网络问题，需要检查网络连接并重试。

步骤3：核心组件安装

# 安装DKMS内核驱动
sudo apt-get install librealsense2-dkms -y  # 安装DKMS内核驱动包，实现内核模块的动态管理

# 安装实用工具（含Realsense Viewer）
sudo apt-get install librealsense2-utils -y  # 安装RealSense实用工具，包括Realsense Viewer

# （可选）安装开发库
sudo apt-get install librealsense2-dev -y  # 安装开发库，用于开发基于RealSense SDK的应用程序

预期结果：DKMS驱动、实用工具和（可选的）开发库安装成功。 风险提示：安装DKMS驱动时可能会出现内核版本不兼容的情况，此时需要检查内核版本是否在支持范围内。

检查点：安装验证

# 检查内核模块加载状态
modinfo uvcvideo | grep "version:"  # 查看uvcvideo内核模块版本，应包含realsense字符串

# 启动可视化验证工具
realsense-viewer  # 启动Realsense Viewer，检查是否能识别相机并显示深度流

预期结果：内核模块版本中包含realsense字符串；Realsense Viewer能够成功启动，识别到RealSense相机并显示深度流。

5.3 普通用户方案：简化安装脚本

步骤1：下载安装脚本

wget https://example.com/realsense_install.sh  # 下载简化安装脚本（此处为示例URL，实际使用时需替换为真实脚本地址）
chmod +x realsense_install.sh  # 为脚本添加可执行权限

预期结果：安装脚本下载成功并添加了可执行权限。 风险提示：确保下载脚本的来源可信，避免下载恶意脚本。可以通过检查脚本的MD5哈希值等方式进行安全验证。

步骤2：运行安装脚本

sudo ./realsense_install.sh  # 以root权限运行安装脚本，脚本将自动完成依赖安装、驱动配置等步骤

预期结果：脚本自动执行安装过程，完成后提示安装成功。 风险提示：安装过程中可能会出现各种错误，脚本应提供详细的错误提示，用户根据提示进行处理。

检查点：设备验证

启动Realsense Viewer，检查相机是否能够正常连接并显示图像。

六、错误解决方案：故障排除决策树

flowchart TD
    A[遇到安装问题?]
    A --> B[是否为DKMS安装?]
    B -->|是| C[错误信息是否包含'modprobe: ERROR: could not insert 'uvcvideo'']
    C -->|是| D[重新安装DKMS包: sudo apt-get install --reinstall librealsense2-dkms]
    C -->|否| E[查看/var/log/librealsense-setup.log日志]
    B -->|否| F[是否为源码编译?]
    F -->|是| G[错误是否为依赖缺失?]
    G -->|是| H[安装缺失的依赖库: sudo apt-get install <缺失的依赖>]
    G -->|否| I[是否为内核补丁问题?]
    I -->|是| J[检查内核版本与补丁兼容性，重新执行对应补丁脚本]
    I -->|否| K[查看编译日志，查找具体错误信息]
    A --> L[Realsense Viewer无图像?]
    L --> M[检查USB端口是否为3.0]
    M -->|否| N[更换为USB 3.0端口]
    M -->|是| O[检查是否使用USB集线器]
    O -->|是| P[直接连接相机到电脑USB端口]
    O -->|否| Q[重新拔插相机或重启电脑]

七、性能优化配置

7.1 USB带宽调整

# 查看当前USB设备配置
lsusb -d 8086: -v | grep "wMaxPacketSize"  # 查看RealSense设备的USB最大数据包大小

# 设置USB3.0最大带宽（需root权限）
echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb  # 增加USBFS内存分配，提高USB带宽

操作建议：此设置在系统重启后会失效，如果需要永久生效，可以将命令添加到/etc/rc.local文件中。

7.2 电源管理优化

# 禁用USB自动挂起
sudo tee /etc/udev/rules.d/80-realsense-power.rules <<EOF
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="8086", ATTR{power/autosuspend}="-1"
EOF  # 创建udev规则，禁止RealSense设备的USB自动挂起
sudo udevadm control --reload-rules && sudo udevadm trigger  # 重新加载udev规则并触发生效

注意事项：禁用USB自动挂起可能会增加设备功耗，但可以避免因设备休眠导致的连接中断问题。

八、验证与测试工具

工具名称	功能描述	调用命令
realsense-viewer	可视化数据流与设备配置	`realsense-viewer`
rs-enumerate-devices	列出设备信息与支持模式	`rs-enumerate-devices -S`
rs-record	录制数据流到文件	`rs-record -o output.bag`
rs-benchmark	性能基准测试	`rs-benchmark`

RealSense Viewer录制界面：可通过该界面录制相机数据流到文件，方便后续分析和处理。

RealSense Viewer回放界面：用于回放已录制的数据流文件，查看历史数据。

九、自动化安装脚本

以下是一个自动化安装脚本的示例（适用于普通用户）：

#!/bin/bash

# 检查是否以root权限运行
if [ "$(id -u)" -ne 0 ]; then
    echo "请以root权限运行此脚本: sudo $0"
    exit 1
fi

# 更新系统
apt-get update && apt-get upgrade -y

# 安装依赖
apt-get install apt-transport-https ca-certificates git cmake build-essential -y
apt-get install libssl-dev libusb-1.0-0-dev libudev-dev pkg-config libgtk-3-dev libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev -y

# 克隆源码
git clone https://gitcode.com/GitHub_Trending/li/librealsense.git
cd librealsense

# 设置权限
./scripts/setup_udev_rules.sh

# 应用内核补丁
./scripts/patch-realsense-ubuntu-lts-hwe.sh

# 编译安装
mkdir build && cd build
cmake .. -DBUILD_EXAMPLES=true -DBUILD_GRAPHICAL_EXAMPLES=true
make -j$(nproc)
make install
ldconfig

echo "Intel® RealSense™ SDK安装完成"

安全验证方法：在运行脚本前，可以通过以下命令检查脚本的MD5哈希值，确保脚本未被篡改：

md5sum realsense_install.sh

将计算出的哈希值与官方提供的哈希值进行对比，如果一致则可以安全运行。

十、版本升级路径指引

如果需要升级Intel® RealSense™ SDK，可以按照以下步骤进行：

源码编译安装升级：
- 进入源码目录：cd librealsense
- 拉取最新代码：git pull
- 重新编译安装：按照源码编译安装的步骤重新执行编译和安装命令。
DKMS预编译包升级：
- 更新软件包索引：sudo apt-get update
- 升级DKMS包：sudo apt-get upgrade librealsense2-dkms