安装问题跟踪器¶

所有已知的安装问题，已合并为独立问题并按严重程度排序。如需失败帮助，请先从故障排查指南开始。实时讨论在 #3836。

截至 2026-11-06，此列表涵盖 515 份 GitHub 报告，合并为 55 个唯一问题。最新版本为 v0.5.7。

如何阅读此列表¶

ID： INST-<category>-<number>。一个 ID 对应一个问题，且不会重复使用。排名可以改变，但 ID 保持不变。
严重程度： 使用仓库的优先级标签。
- P0：阻止许多用户首次运行或核心使用。
- P1：破坏或降低核心工作流。
- P2：重要改进或令人困惑的设置。
- P3：锦上添花或打磨。
已修复 表示修复 PR 已合并。这并不表示修复已在每个平台上重新测试。仅就问题发出警告或解释问题的 PR 不算修复。

状态	含义
未修复	尚无修复
部分修复	早期报告已修复，但较新的报告仍未解决
已在主分支修复	最新修复在 v0.5.7 之后合并，将在下一个版本中发布
已在版本中修复	所有关联修复都包含在 v0.5.7 或更早版本中
已拒绝	我们选择不修复；“后续步骤”列说明了原因
已关闭，原因未知	在未确认原因的情况下关闭，通常是因为报告中没有日志

分类¶

每个类别都有一个 GitHub 标签，下面的每份报告都带有该标签。

代码	类别	标签
`WIN`	Windows 权限与安装程序	`install:windows`
`NET`	网络与依赖项下载	`install:network`
`NATIVE`	原生崩溃	`install:native-crash`
`BOOT`	后端启动	`install:backend-startup`
`AMD`	AMD GPU 设置	`install:amd`
`NVDA`	NVIDIA GPU 设置	`install:nvidia`
`MAC`	macOS	`install:macos`
`LNX`	Linux	`install:linux`
`SRC`	从源码运行	`install:source`
`SCRIPT`	安装脚本	`install:script`
`DOCK`	Docker	`install:docker`
`MODEL`	模型下载	`install:models`
`ENG`	引擎安装	`install:engines`
`DEP`	系统依赖项	`install:dependencies`
`UX`	设置界面	`install:setup-ui`
`UPD`	更新与卸载	`install:update`

摘要¶

状态	唯一问题数
未修复	8
部分修复	10
已在主分支修复	11
已在版本中修复	23
已拒绝	1
已关闭，原因未知	2

排名列表¶

排名	ID	严重程度	问题	状态	修复	后续步骤	帮助	报告数
1	`INST-WIN-001`	P0	Windows Smart App Control 或杀毒软件阻止了未签名的 Python 文件（`spawn UNKNOWN`）	部分修复	#3640, #3810	需要签名的 Python 文件（#1779）。目前关闭 Smart App Control 即可。已合并的 PR 仅发出警告并指出拦截来源。	`WINDOWS_APP_CONTROL_BLOCKED`	53
2	`INST-NATIVE-001`	P0	Windows 后端在加载 torch 或模型数据时因访问冲突而崩溃	部分修复	#2467, #2499, #3385	需要找到 torch 模型加载中的根本原因。#3507 处理的是另一个安装崩溃。	`NATIVE_ACCESS_VIOLATION`	16
3	`INST-NET-001`	P0	Torch 或依赖项下载在慢速或受限网络上停滞、重启或失败	已在主分支修复	#3557, #3576, #3785	在下一个版本中重新测试，然后关闭仍未解决的问题。	`RUNTIME_DOWNLOAD_STALLED`	12
4	`INST-MAC-001`	P0	macOS 提示应用已损坏或安装后无法打开	已在版本中修复	#3033, #3243		`GATEKEEPER_QUARANTINE`	9
5	`INST-BOOT-001`	P1	端口 3900 已被占用或无法绑定	部分修复	#1982, #2362, #3025	现在保留端口可以恢复，但被其他应用占用的端口仍会阻止启动。请改用空闲端口。	`PORT_IN_USE`	7
6	`INST-AMD-001`	P1	系统检查报告 `ROCm not configured`，或 Linux ROCm 设置失败	部分修复	#3553, #3602	AMD 上的设置流程仍要求提供环境变量。请在设置中提供 ROCm 选项。	`ROCM_NOT_CONFIGURED`	7
7	`INST-BOOT-002`	P1	后端在启动时限内未响应端口 3900	部分修复	#1232, #2283, #2461	需要找到 macOS 上的根本原因。目前开放的 #3724 只是改进诊断。	`STARTUP_TIMEOUT_SILENT`	7
8	`INST-AMD-002`	P1	Linux gfx103x：HSA 覆盖应用得太晚，且 ROCm 选择未被保留	部分修复	#1666, #2424, #2501	更早应用覆盖，并保留 ROCm 选择。	`ROCM_NOT_CONFIGURED`	3
9	`INST-NET-002`	P1	安装程序在代理配置步骤处停止，或将代理问题误报为 DNS 问题	部分修复	#2245	修复安装流程，使其在完成代理步骤后继续执行。	`RUNTIME_DOWNLOAD_INTERRUPTED`	3
10	`INST-AMD-003`	P1	Linux AMD 引擎需要匹配的 ROCm torch 和如实的路由	部分修复	#2501	审查未关闭的 #3787。	`ROCM_NOT_CONFIGURED`	3
11	`INST-NATIVE-002`	P1	在 Windows 上，后端因堆损坏而退出	未修复		找出根本原因。	`NATIVE_CRASH`	1
12	`INST-BOOT-003`	P1	后端在安装界面空闲约两分钟后退出	未修复		查明后端在安装程序空闲时退出的原因。未关闭的 #3727 仅解释了退出代码。	`BACKEND_STARTUP_FAILED`	1
13	`INST-NATIVE-003`	P1	在较旧的 CPU 上，后端因非法指令而退出	未修复		找出根本原因。	`NATIVE_ILLEGAL_INSTRUCTION`	1
14	`INST-BOOT-004`	P1	后端已运行，但在启动期间在端口 3900 上停止响应	已在 main 分支修复	#3119, #3185, #3595	将在下个版本中发布。	`STARTUP_TIMEOUT_OUTPUT`	30
15	`INST-BOOT-005`	P1	运行时在安装后不完整，导致启动时因缺少 Python 模块而失败	已在 main 分支修复	#3508, #3552, #3595	将在下个版本中发布。	`BROKEN_VENV`	20
16	`INST-MODEL-001`	P1	模型下载失败：SSL 错误、镜像重定向、代理和错误的缓存路径	已在 main 分支修复	#890, #1312, #3622	将在下个版本中发布。	下载模型	10
17	`INST-NVDA-001`	P1	捆绑的 torch 构建不支持旧款或非常新的 NVIDIA GPU	已在 main 分支修复	#1997, #2149, #3553	将在下个版本中发布。	第 5a 节, 第 5b 节	10
18	`INST-NATIVE-004`	P1	在 Windows 上，运行时安装在 CUDNN8 探测时崩溃	已在 main 分支修复	#3025, #3507	将在下个版本中发布。	`NATIVE_ACCESS_VIOLATION`	8
19	`INST-ENG-001`	P1	CosyVoice 3：一键安装提示成功，但无法生成	已在 main 分支修复	#94, #3553	将在下个版本中发布。	第 11 节	4
20	`INST-WIN-002`	P1	在 Windows 上重命名运行时文件时发生 `EPERM`	已在 main 分支修复	#3023, #3507	将在下个版本中发布。	`RUNTIME_FILES_LOCKED`	4
21	`INST-BOOT-006`	P1	启动在 `api_routes` 中失败，报错 `'NoneType' object has no attribute 'splitlines'`	已在 main 分支修复	#3615	在下个版本发布后关闭 #3818。	`BACKEND_STARTUP_FAILED`	2
22	`INST-MODEL-002`	P1	语音克隆失败，因为未安装语音转文本模型	已在发布版本中修复	#2444, #2498, #2602			11
23	`INST-WIN-003`	P1	安装程序忽略所选驱动器，或在默认位置之外安装时失败	已在发布版本中修复	#1795, #2500, #3024		`RUNTIME_FOLDER_DENIED`	9
24	`INST-LNX-001`	P1	AppImage 或 deb 打开后显示空白窗口，或根本无法启动	已在发布版本中修复	#93, #1265		第 4 节	9
25	`INST-BOOT-007`	P1	启动在 `ml_imports` 中失败，因为 torch DLL 缺失或不完整	已在发布版本中修复	#3150		`BROKEN_VENV`	6
26	`INST-MODEL-003`	P1	下载不完整的模型被显示为已安装	已在发布版本中修复	#626, #2673, #3116			5
排名	ID	严重程度	问题	状态	修复	下一步	帮助	报告数
27	`INST-SCRIPT-001`	P1	一键安装脚本失败或提供的脚本有误	已在发布版中修复	#61, #1627, #1815		script.md	5
28	`INST-DOCK-001`	P1	Docker 镜像无法构建或启动	已在发布版中修复	#27, #2072		docker.md	3
29	`INST-UPD-001`	P1	更新后应用无法启动	已在发布版中修复	#1754			1
30	`INST-MAC-002`	P1	Intel Mac 无法为本地后端安装 torch	已拒绝		Intel Mac 可按照 macos.md 的说明，使用远程后端运行应用。	`UNSUPPORTED_PLATFORM`	5
31	`INST-SRC-001`	P2	从源码运行：Python 环境缺失或不完整	部分修复	#2602	等待报告人提供详细信息（#3589）。	`SOURCE_ENV_INCOMPLETE`	12
32	`INST-AMD-004`	P2	Windows ROCm：引擎对等性仍有差距	部分修复	#3045	补齐剩余的引擎差距。开放的 PR：#3734 和 #3486（等待签署 CLA）。	windows-rocm.md	2
33	`INST-WIN-004`	P2	Windows Defender 会阻止状态保存，导致最新的崩溃记录丢失	未解决		审查开放的 #3708。	`ANTIVIRUS_BLOCKED`	1
34	`INST-LNX-002`	P2	应用在 NixOS 上无法打开	未解决		查明应用在 NixOS 上失败的原因。	nix.md	1
35	`INST-AMD-005`	P2	Windows RDNA 2 需要可用的原生 torch、就绪检查以及安全的 CPU 回退方案	未解决		审查开放的 #3712。	windows-rocm.md	1
36	`INST-AMD-006`	P2	Windows Vulkan 检测在隐藏探测时超时	未解决		审查开放的 #3648。		1
37	`INST-UX-001`	P2	首次运行设置界面会阻塞或误导（`All good` 置灰、步骤重复）	已在主分支修复	#1992, #3378, #3595	将在下一个版本中发布。		14
38	`INST-WIN-005`	P2	Windows 安装程序提示 VoiceStudio 仍在运行，或无法完成安装	已在主分支修复	#3621, #3624, #3636	将在下一个版本中发布。		6
39	`INST-ENG-002`	P2	其他引擎安装失败（Confucius4、dots.tts、Nemo、pyannote、翻译）	已在发布版中修复	#2173, #2181, #2484			11
40	`INST-LNX-003`	P2	Linux 包：deb 文件冲突、libfuse、更新和麦克风	已在发布版中修复	#93, #1681, #2329		第 7 节	7
41	`INST-DEP-001`	P2	FFmpeg 缺失或在设置过程中无法检测到	已在发布版中修复	#716, #1311, #2353		第 7b 节	6
42	`INST-DOCK-002`	P2	Docker：远程浏览器、回环检查和共享 PIN 会阻止访问	已在发布版中修复	#93, #1673, #3401		第 8 节	4
43	`INST-NATIVE-005`	P2	后端在 Windows 上因堆栈缓冲区溢出而退出	已在发布版中修复	#1401, #2907		`NATIVE_CRASH`	4
44	`INST-ENG-003`	P2	IndexTTS：一键安装构建了错误的环境或权重配置	已在发布版中修复	#2205, #2207, #2240		第 11 节	3
45	`INST-MAC-003`	P2	后端在 Apple Silicon 上首次加载模型时挂起或失败	已在发布版中修复	#645, #1310, #1657			3
46	`INST-DOCK-003`	P2	Docker：未检测到 AMD GPU，或没有对应的镜像	已在发布版中修复	#1166, #1673		docker.md	2
47	`INST-DOCK-004`	P2	Docker：没有适用于主机的 ARM64 镜像	已在发布版中修复	#1988, #3402	标准镜像仍然没有原生 ARM64 构建：#1988 记录了模拟方案，#3402 增加了 NVIDIA 镜像。	docker.md	2
48	`INST-ENG-004`	P2	MOSS-TTS 引擎无法安装或没有音频后端	已在发布中修复	#2016, #2182			2
49	`INST-BOOT-008`	P2	较早的后端启动报告未记录原因（在失败代码出现之前）	已关闭，原因未知		根本原因记录在 #602 中。	`BACKEND_STARTUP_FAILED`	153
50	`INST-UX-002`	P3	安装程序未明确说明哪些模型允许商业使用	开放		回答问题并决定安装程序是否应显示此信息。		1
51	`INST-SRC-002`	P3	Google Colab 笔记本安装中断	已在发布中修复	#1923			4
52	`INST-SRC-003`	P3	源代码安装命令失败（`bun run`、Python 版本、wheels）	已在发布中修复	#1444, #2080			4
53	`INST-DOCK-005`	P3	Docker：镜像标签落后于发布版本或让用户困惑	已在发布中修复	#252		docker.md	2
54	`INST-UPD-002`	P3	卸载后用户不确定如何移除应用	已在发布中修复	#1097		uninstall.md	1
55	`INST-UX-003`	P3	非常早期的安装报告，未记录原因	已关闭，原因未知				3

每个问题的报告¶

开放的报告已附带链接。通过搜索编号可找到已关闭的报告。

ID	GitHub 报告
`INST-WIN-001`	#3801, #3789, #3788, #3783, #3779, #3778, #3756, #3739, #3714, #3698, #3697, #3696, #3686, #3683, #3682, #3681, #3672, #3668, #3650, #3635, #3633, #3632, #3506, #3371, #3351, #3337, #3329, #3326, #3322, #3272, #3224, #3209, #3204, #3201, #3200, #3196, #3169, #3163, #3156, #3146, #3106, #3103, #3084, #3081, #3077, #3063, #3061, #2981, #2959, #2949, #2839, #2440, #1712
`INST-NATIVE-001`	#3772, #3767, #3340, #3267, #3226, #3043, #2416, #2394, #2189, #1939, #1927, #1777, #1708, #1669, #1275, #1069
`INST-NET-001`	#3820, #3748, #3720, #3475, #3444, #3411, #3259, #3202, #3060, #2562, #569, #130
`INST-MAC-001`	#3264, #3240, #2951, #2829, #2763, #2681, #2360, #79, #54
`INST-BOOT-001`	#3704, #3020, #2358, #1974, #1637, #1635, #1364
`INST-AMD-001`	#3780, #3627, #3158, #1629, #1582, #972, #124
`INST-BOOT-002`	#3713, #2985, #2445, #2276, #2184, #1909, #1229
`INST-AMD-002`	#3804, #2372, #1665
`INST-NET-002`	#3741, #2114, #33
`INST-AMD-003`	#3786, #2373, #2371
`INST-NATIVE-002`	#3835
`INST-BOOT-003`	#3680
`INST-NATIVE-003`	#3684
`INST-BOOT-004`	#3558, #3488, #3460, #3364, #3342, #3306, #3245, #3229, #3228, #3222, #3214, #3184, #3182, #3173, #3139, #3108, #3085, #3072, #3059, #2970, #2876, #2840, #2794, #2756, #2610, #2601, #2594, #2491, #2490, #2430
`INST-BOOT-005`	#3584, #3551, #3480, #3367, #3121, #2237, #2176, #2128, #1832, #1642, #1587, #1415, #1376, #1282, #1231, #1185, #1156, #314, #307, #129
`INST-MODEL-001`	#3620, #2045, #1335, #1301, #976, #959, #874, #239, #118, #117
`INST-NVDA-001`	#3067, #2135, #1931, #1812, #1529, #1349, #1343, #1342, #1285, #756
`INST-NATIVE-004`	#3293, #3015, #2960, #2957, #2942, #2382, #2270, #2250
`INST-ENG-001`	#3423, #2096, #1746, #55
`INST-WIN-002`	#3409, #3050, #3010, #2669
`INST-BOOT-006`	#3818, #3612
`INST-MODEL-002`	#3369, #3176, #3122, #2929, #2678, #2579, #2442, #2322, #2319, #2132, #2116
`INST-WIN-003`	#3070, #2971, #2683, #2436, #1783, #1713, #1223, #938, #766
`INST-LNX-001`	#2146, #1258, #1244, #971, #961, #222, #144, #127, #56
`INST-BOOT-007`	#3370, #3301, #3147, #3058, #3055, #3051
`INST-MODEL-003`	#3112, #2634, #2386, #1273, #622
`INST-SCRIPT-001`	#3274, #2973, #2754, #1813, #1626
`INST-DOCK-001`	#2050, #43, #5
`INST-UPD-001`	#1749
`INST-MAC-002`	#3225, #3198, #2598, #2365, #889
`INST-SRC-001`	#3722, #3589, #3261, #2988, #2948, #2922, #2787, #2783, #2621, #2555, #2465, #2303
`INST-AMD-004`	#3123, #2468
`INST-WIN-004`	#3705
`INST-LNX-002`	#3823
`INST-AMD-005`	#3770
`INST-AMD-006`	#3645
`INST-UX-001`	#3581, #2940, #1900, #1894, #1886, #1884, #1856, #1851, #1849, #1848, #1847, #1845, #1514, #1496
`INST-WIN-005`	#3614, #3566, #3115, #1946, #1714, #1140
`INST-ENG-002`	#3638, #2479, #2163, #2101, #2099, #2019, #1029, #974, #529, #527, #186
`INST-LNX-003`	#2328, #2327, #2063, #1682, #1680, #1333, #76
`INST-DEP-001`	#2345, #2215, #2167, #2124, #1309, #712
`INST-DOCK-002`	#3628, #3003, #1651, #80
`INST-NATIVE-005`	#2904, #1409, #1372, #1371
`INST-ENG-003`	#2098, #2097, #1428
`INST-MAC-003`	#1656, #1266, #632
`INST-DOCK-003`	#1655, #1165
`INST-DOCK-004`	#2831, #1921
`INST-ENG-004`	#2100, #2015
`INST-BOOT-008`	#3206, #2493, #2385, #2248, #2247, #2136, #2134, #2079, #2055, #2054, #1953, #1936, #1935, #1934, #1933, #1875, #1850, #1842, #1828, #1814, #1802, #1705, #1701, #1698, #1697, #1690, #1663, #1661, #1658, #1586, #1583, #1579, #1578, #1572, #1535, #1510, #1509, #1478, #1439, #1435, #1378, #1365, #1351, #1345, #1337, #1336, #1323, #1293, #1261, #1259, #1243, #1224, #1177, #1164, #1157, #1153, #1133, #1124, #1118, #1113, #1109, #1101, #1093, #1092, #1090, #1076, #1044, #1011, #1000, #979, #948, #941, #929, #926, #903, #900, #897, #885, #876, #875, #873, #863, #853, #850, #821, #809, #806, #804, #802, #796, #786, #785, #769, #755, #746, #743, #740, #738, #737, #736, #735, #729, #728, #727, #725, #724, #723, #721, #689, #682, #681, #680, #663, #662, #652, #638, #636, #628, #627, #624, #623, #620, #619, #618, #613, #610, #602, #597, #592, #591, #588, #585, #584, #583, #582, #580, #571, #570, #567, #555, #553, #548, #546, #541, #540, #535, #534, #522, #521, #520, #515, #514, #491
`INST-UX-002`	#3745
`INST-SRC-002`	#1922, #1357, #1341, #1294
`INST-SRC-003`	#2113, #2052, #1438, #962
`INST-DOCK-005`	#251, #249
`INST-UPD-002`	#1089
`INST-UX-003`	#57, #35, #4

保持此列表最新¶

已知问题的新报告： 将该编号添加到该问题所在行，更新计数，并添加类别标签。
新问题： 在其类别中添加一行，使用下一个编号，并保持列表按严重程度排序。
修复已合并： 将状态设置为 Fixed on main 并链接相应的 PR。
发布已切出： 将 Fixed on main 改为 Fixed in release，并更新本页顶部所标注的发布版本。

tests/test_install_issue_tracker.py 检查 ID、顺序、状态、链接和报告数量。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 om/VoiceStudio