StarBox

主题

常见问题 ​

这里汇总了 StarBox 使用过程中的常见问题和解决方案。

找不到答案？

📦 安装相关 ​

Windows 提示"无法验证发布者" ​

问题描述：双击安装包时，Windows 提示"无法验证发布者"或"Windows 已保护你的电脑"。

解决方案：

  1. 右键点击安装文件
  2. 选择"属性"
  3. 勾选"解除锁定"
  4. 点击"应用" → "确定"
  5. 再次双击运行安装程序

或者在弹出的提示窗口中：

  1. 点击"更多信息"
  2. 点击"仍要运行"

macOS 提示"无法打开，因为无法验证开发者" ​

问题描述：打开 StarBox 时，macOS 提示"无法打开 StarBox，因为无法验证开发者"。

解决方案：

方法一（推荐）：

  1. 打开"系统偏好设置"
  2. 进入"安全性与隐私"
  3. 在"通用"选项卡中，找到关于 StarBox 的提示
  4. 点击"仍要打开"

方法二：

  1. 右键点击 StarBox 应用
  2. 选择"打开"
  3. 在弹出的对话框中点击"打开"

方法三（终端命令）：

bash
sudo xattr -rd com.apple.quarantine /Applications/StarBox.app

Linux 提示 glibc 版本错误 ​

问题描述：运行 StarBox 时提示 version 'GLIBC_2.31' not found 或类似错误。

解决方案：

StarBox 需要 glibc 2.31 或更高版本。请升级到以下系统版本：

  • Ubuntu 22.04 或更高
  • Debian 11 或更高
  • Fedora 35 或更高

检查当前 glibc 版本：

bash
ldd --version

如果无法升级系统，建议使用 Docker 容器运行 StarBox。

Embedded 版本端口被占用 ​

问题描述：启动 Embedded 版本时提示端口 23450 被占用。

解决方案：

方法一：使用其他端口

bash
# Windows
starbox-embedded-windows-{version}.exe --port 8080

# macOS/Linux
./starbox-embedded-macos-{version} --port 8080

方法二：停止占用端口的程序

Windows:

bash
# 查找占用端口的进程
netstat -ano | findstr :23450

# 结束进程（替换 PID 为实际进程 ID）
taskkill /PID <PID> /F

macOS/Linux:

bash
# 查找占用端口的进程
lsof -i :23450

# 结束进程（替换 PID 为实际进程 ID）
kill -9 <PID>

🔧 FFmpeg 相关 ​

FFmpeg 未找到 ​

问题描述：启动 StarBox 后提示"FFmpeg 未找到"或音频处理失败。

解决方案：

  1. 确认已安装 FFmpeg
  2. 验证 FFmpeg 是否在系统路径中：
    bash
    ffmpeg -version
  3. 如果已安装但仍提示未找到，重启 StarBox
  4. 如果问题依然存在，重新安装 FFmpeg

详细安装步骤请查看 快速开始 - FFmpeg 安装。

FFmpeg 安装后仍然不可用 ​

问题描述：已安装 FFmpeg 并验证可用，但 StarBox 仍提示未找到。

解决方案：

  1. 完全退出 StarBox（包括系统托盘）
  2. 重启 StarBox
  3. 如果问题依然存在，尝试重启电脑

Windows 用户额外步骤：

  • 确认 FFmpeg 已添加到系统环境变量 PATH
  • 在命令提示符（CMD）中运行 ffmpeg -version 验证

🖥️ 界面相关 ​

文本编辑时 UI 错乱 ​

问题描述：编辑文本时界面显示错乱或布局异常。

解决方案：

  1. 刷新页面（Electron 客户端：Ctrl/Cmd + R）
  2. 切换到其他页面再返回
  3. 重启 StarBox

🔌 插件相关 ​

音频插件下载失败 ​

问题描述：在插件市场下载插件时失败或超时。

解决方案：

  1. 检查网络连接
  2. 尝试使用代理或 VPN（已开启关闭后再尝试）
  3. 手动下载插件文件并导入

📝 项目相关 ​

项目创建失败 ​

问题描述：创建新项目时提示失败或无法创建。

可能原因及解决方案：

  1. 文本格式不支持

    • 解决方案：确保使用 UTF-8 编码的 TXT 文件

  2. 文件过大

    • 解决方案：将大文件分割成多个章节

  3. 磁盘空间不足

    • 解决方案：清理磁盘空间

  4. 权限问题

    • 解决方案：以管理员权限运行 StarBox

多音字配置不生效 ​

问题描述：页面配置了多音字配音，但生成音频时未生效。

解决方案：

  1. 多音字方案为"换成同音字"时，请确保应用配置中配置了拼音替换
  2. 其他多音字方案，请确保对应TTS支持

🔄 更新相关 ​

自动更新失败 ​

问题描述：软件提示有新版本，但自动更新失败。

解决方案：

  1. Windows 用户：使用自动更新功能
  2. macOS 用户：需要手动下载新版本
  3. 访问 下载页面 手动下载最新版本
  4. 检查网络连接

💾 数据相关 ​

应用数据存储位置 ​

本项目使用SQLite存储数据。 SQLite 数据库文件存储在以下目录中：

shell
用户目录\.starbox\db\starbox.sqlite

音频文件存储位置 ​

默认存储在以下目录中：

shell
用户目录\starbox

如果修改过应用数据存储位置，可以在应用设置=>存储页面中查看。

数据备份 ​

备份数据库文件和音频文件夹。

数据恢复 ​

恢复数据库文件和音频文件夹。

重要

数据库文件和音频文件夹需要恢复到原始位置。

🌐 网络相关 ​

无法连接到 LLM 服务 ​

问题描述：配置了文本大模型，但无法连接或调用失败。

解决方案：

  1. 检查 API 地址是否正确
  2. 验证 API Key 是否有效
  3. 检查网络连接
  4. 确认 API 服务是否正常运行
  5. 查看错误日志获取详细信息

无法连接到 TTS 服务 ​

问题描述：音频生成时提示无法连接到 TTS 服务。

解决方案：

  1. 确认 TTS API 服务已启动
  2. 检查端口配置是否正确
  3. 验证服务地址是否可访问
  4. 查看 TTS 服务的日志

📱 其他问题 ​

如何查看日志文件 ​

日志文件位置：

Electron 客户端：

  • Windows: %APPDATA%\starbox\logs\
  • macOS: ~/Library/Logs/starbox/
  • Linux: ~/.config/starbox/logs/

Embedded 版本：

  • 所有平台: 可执行文件同目录下的 logs/starbox-server.log

查看方法： 使用文本编辑器打开日志文件，查找错误信息。

如何完全卸载 StarBox ​

Windows:

  1. 通过"设置" → "应用"卸载 StarBox
  2. 删除数据目录：%APPDATA%\starbox\

macOS:

  1. 将 StarBox 从 Applications 文件夹移到废纸篓
  2. 删除数据目录：~/Library/Application Support/starbox/
  3. 删除日志目录：~/Library/Logs/starbox/

Linux:

bash
# DEB 包
sudo apt remove starbox

# Snap 包
sudo snap remove starbox

# AppImage
直接删除 .AppImage 文件

# 删除数据目录
rm -rf ~/.config/starbox/

🆘 仍然无法解决？ ​

如果以上方案都无法解决你的问题：

  1. 📋 收集信息：

    • StarBox 版本号
    • 操作系统版本
    • 错误信息截图
    • 日志文件内容

  2. 📖 查看文档：

  3. 💬 寻求帮助：

    通过提供的联系信息寻求帮助。

希望这些解答能帮助到你！
如有其他问题，欢迎随时联系我们 💬

BiliBili: Sparks00 | QQ 群: 751706992

Copyright © 2025-present StarBox