666666999999 - 技术栈

树莓派的 Chromium Kiosk（信息亭）模式 是实现"开机全屏运行 Web 应用"的最常用、最成熟的方案，广泛用于数字标牌、自助终端、控制面板等场景。以下是完整、可落地、经过社区验证的配置指南 ，适用于 Raspberry Pi OS（原 Raspbian）桌面版（Bookworm 或 Bullseye）。

✅ 一、前提条件

系统要求：
- 使用 Raspberry Pi OS with desktop（非 Lite 版本）；
- 推荐 Bookworm（2023 年后发布），兼容性更好；
- 设备：树莓派 3B+ / 4 / 5（Pi 2 可能卡顿）。
已安装 Chromium 浏览器（Raspberry Pi OS 桌面版默认已预装）：
bash 复制代码
```
chromium-browser --version
```

🔧 二、核心配置步骤

步骤 1：启用自动登录到桌面

避免每次启动需手动登录。

bash 复制代码

sudo raspi-config

操作路径：

System Options → Boot / Auto Login → Desktop (Autologin)
💡 注意：不要选 "Console Autologin"，Kiosk 模式需要图形界面。

重启生效：

bash 复制代码

sudo reboot

步骤 2：创建 Kiosk 启动脚本

在 /home/pi/ 下创建脚本文件：

bash 复制代码

nano ~/kiosk.sh

填入以下内容（支持本地或远程 URL）：

bash 复制代码

#!/bin/sh

# 禁用屏幕保护和节能
xset s off        # 关闭屏幕保护
xset -dpms        # 关闭 DPMS（显示器电源管理）
xset s noblank    # 禁止黑屏

# 自动隐藏鼠标（闲置即消失）
unclutter -idle 0 &

# 启动轻量窗口管理器（无标题栏、任务栏）
matchbox-window-manager -use_titlebar no &

# 等待图形环境就绪
sleep 2

# 启动 Chromium 全屏浏览器
chromium-browser \
  --no-first-run \
  --disable-infobars \
  --disable-session-crashed-bubble \
  --disable-restore-session-state \
  --noerrdialogs \
  --incognito \
  --kiosk \
  --start-fullscreen \
  --enable-features=OverlayScrollbar \
  http://localhost:8080

📌 URL 替换建议：

本地 Web 服务：http://localhost:8080

本地 HTML 文件：file:///home/pi/myapp/index.html

远程网页：https://your-domain.com/kiosk

保存并退出（Ctrl+O → Enter → Ctrl+X）。

赋予执行权限：

bash 复制代码

chmod +x ~/kiosk.sh

步骤 3：配置开机自启动

方法 A：通过 LXDE autostart（推荐）

bash 复制代码

mkdir -p ~/.config/autostart
nano ~/.config/autostart/kiosk.desktop

填入：

ini 复制代码

[Desktop Entry]
Type=Application
Name=Kiosk Mode
Exec=/home/pi/kiosk.sh
X-GNOME-Autostart-enabled=true

✅ 此方法在用户登录桌面后自动执行，兼容性最好 ty-reference。

方法 B（备用）：修改全局 autostart（若方法 A 失效）

bash 复制代码

sudo nano /etc/xdg/lxsession/LXDE-pi/autostart

在文件末尾添加：

bash 复制代码

@/home/pi/kiosk.sh

⚠️ 若想完全跳过桌面（不显示任务栏），可注释掉 @lxpanel 行，但通常不必要。

步骤 4：部署你的 Web 应用（可选）

如果你的应用是本地的，需启动一个 Web 服务器：

示例：用 Python 快速启动

bash 复制代码

cd /home/pi/myapp
python3 -m http.server 8080

或使用 Node.js、Flask、Nginx 等长期服务（建议用 systemd 托管）。

💡 提示：若使用 file:// 协议加载本地 HTML，注意浏览器安全策略可能限制 AJAX、localStorage 等功能，强烈建议使用本地 HTTP 服务。

🔒 三、增强稳定性与用户体验

1. 防止 Chromium 崩溃后白屏

在脚本中加入循环重启机制（可选）：

bash 复制代码

while true; do
  chromium-browser --kiosk --noerrdialogs http://localhost:8080
  sleep 5
done

2. 隐藏鼠标光标更彻底

除了 unclutter，也可在 CSS 中加：

css 复制代码

html, body {
  cursor: none !important;
}

3. 禁用右键菜单、F11 等快捷键

Chromium 的 --kiosk 模式已禁用大部分退出方式，但可进一步加固：

使用前端 JavaScript 屏蔽按键：

js 复制代码

document.addEventListener('keydown', e => {
  if ([122, 123, 116].includes(e.keyCode)) e.preventDefault(); // F11, F12, F5
});

或使用 --app 模式（但功能略弱于 --kiosk）。

4. 网络就绪再启动

若依赖网络，可在脚本开头加等待逻辑：

bash 复制代码

while ! ping -c1 google.com &>/dev/null; do sleep 1; done

🔄 四、调试与故障排查

问题	解决方案
黑屏或未启动	检查 `~/.xsession-errors` 日志
鼠标仍可见	确认 `unclutter` 已安装：`sudo apt install unclutter`
Chromium 闪退	移除 `--incognito` 测试；检查 URL 是否可访问
无法全屏	确保未启用"Desktop Autologin"以外的登录方式
内存不足	关闭其他桌面组件（如 `pcmanfm`、`lxpanel`）

安装必要工具：

bash 复制代码

sudo apt update
sudo apt install unclutter matchbox x11-xserver-utils

✅ 五、最终效果

树莓派通电 → 自动登录桌面 → 立即全屏打开指定网页；
无地址栏、无标签页、无右键菜单；
鼠标自动隐藏，屏幕永不休眠；
用户无法轻易退出或访问系统。

📚 参考资料

CSDN 实测教程：使用 xinit + .bashrc 方案 ty-reference；
官方 Raspberry Pi 论坛推荐 autostart 方式 ty-reference；
Chromium Kiosk 参数文档：chromium-browser --help

通过以上配置，你可以在 30 分钟内 将树莓派变成一个专业级的信息亭设备。此方案已在广告屏、工厂看板、博物馆导览等场景大规模应用，稳定可靠。