---
title: "DSH Web UI 启动失败：从环境到端口逐项排查"
seo_title: "DSH Web UI 启动失败：从环境到端口逐项排查"
description: "DSH 安装卡住或 Web UI 打不开时，按 npx 下载、ETARGET、pnpm PATH、服务启动、浏览器连接和模型任务六个阶段排查。"
canonical: https://52dsh.com/errors/web-ui-start-failed/
authors: ["52DSH 编辑部"]
audience: ["DSH Web UI 无法打开或无法继续使用的用户"]
outcomes: ["按症状确定错误发生阶段","进入对应的精确修复页面"]
prerequisites: ["保留完整错误原文"]
difficulty: beginner
estimated_action_time: "5～15 分钟"
next_steps: {"success":["/tutorials/deepseek-harness-install-web-ui/","/errors/"],"failure":["/search/?q=DSH%20Web%20UI%20启动失败"]}
published_at: 2026-08-18
updated_at: 2026-09-30
verified_on: 2026-09-10
maintenance_status: community
verification_level: source_reviewed
risk_level: low
dsh_version: 0.1.1-rc.2
plugin_id: null
tutorial_kind: null
related_plugin_url: null
---

# DSH Web UI 启动失败：从环境到端口逐项排查

DSH 安装卡住或 Web UI 打不开时，按 npx 下载、ETARGET、pnpm PATH、服务启动、浏览器连接和模型任务六个阶段排查。

DSH 启动失败时，先保存启动命令和第一条具体错误，再区分服务未启动、浏览器连接失败与任务执行失败。下面先按症状定位；版本专项说明保留各自范围，本站未运行这些 DSH 故障复现。

## 先保存完整错误原文

保存执行的命令、工作目录、第一条错误、最后一条错误、运行时版本和操作系统。截图适合保留界面，但可复制的错误文本更适合搜索和比较。

在公开求助前删除用户名、目录中的客户名称、Token、Cookie、内网地址和其他敏感信息。

## 先判断你属于哪一种情况

不要把“DSH 不能用”当成一个错误。先对照可观察症状，再进入精确页面：

| 你看到的症状 | 可观察判断 | 下一步 |
|---|---|---|
| `node`、`npx` 或 `dsh` 命令不可用，或版本不满足要求 | `node --version` 无结果或不在 `^22.19.0 \|\| >=24.0.0` | [检查 Node 环境](/errors/dsh-node-version-error/) |
| Node 版本符合要求，但 Web 白屏或加载异常 | 记录 Node/DSH 版本和客户端加载错误；Node 24.0–24.11.1 有特定修复线索 | [区分版本声明与加载器缺陷](/errors/dsh-node-version-error/) |
| 页面曾正常使用，随后连接中断 | 检查 Host 是否仍运行，区分断线与模型请求失败 | [页面已打开，但连接中断](#页面已打开但连接中断) |
| 0.1.1-rc.2 或 0.1.2-alpha.3 能启动，升级 0.1.2-alpha.4 后立即失败 | 保留来源版本、启动日志、Profile 和 Session 副本，不先清缓存 | [升级后立即失败](#从-rc2-或-alpha3-升级-alpha4-后立即失败)，核对 0.1.2-alpha.5 |
| 终端明确出现 3080 地址已被使用 | 3080 已有监听进程 | [检查并切换端口](/errors/dsh-port-3080-in-use/) |
| 页面能打开，但输入框灰色 | 先核对 Session 的 Workspace 和模型选择 | [选择 Workspace](/errors/dsh-workspace-not-selected/) |
| 输入框可用，但中文组合输入异常 | 记录系统、浏览器、输入法及粘贴是否正常，不能直接归因于 Workspace | 保留复现步骤与客户端错误，再核对对应版本问题 |
| 页面能打开，但出现 401、`MISSING_CREDENTIAL` 或 `UNKNOWN_MODEL` | Provider、凭据或模型路由未完成 | [配置模型与 Provider](/tutorials/deepseek-harness-model-provider/) |
| 安装 Git 插件时出现 `allowBuilds` 或构建脚本被阻止 | pnpm 没有批准该包的构建脚本 | [处理插件 allowBuilds](/errors/dsh-plugin-allowbuilds-blocked/) |

如果症状不在表中，继续按下面的顺序保存证据和缩小范围，不要同时修改多个配置。

2026-08-31 复核了 0.1.2-alpha.2 的连接指示与恢复入口，基础启动命令仍按 `0.1.1-rc.2` 阅读。以下是官方固定来源的静态说明，没有把本站 Web 页面测试当成 DSH 本身的运行实测。

## 出现 web exited with code 1，先看哪条错误

`web exited with code 1` 表示进程以失败状态退出，仅凭这一行不能确定根因。先保存它之前的第一条具体错误、原始启动命令、DSH/Node 版本及 Profile，再对照上方症状表。

- 还未出现可访问地址：按[安装与服务启动阶段](#安装卡住etarget-与-pnpm-找不到先确定失败阶段)检查；明确端口占用时进入[端口排障](/errors/dsh-port-3080-in-use/)。
- 日志出现 `Full diagnostics`：读取终端给出的实际路径；[0.1.6-alpha.2 日志说明](#016-alpha2启动错误与日志)只覆盖该版本已核实的诊断实现，不给所有版本猜同一个目录。
- 进程仍在运行但浏览器打不开：核对实际地址与连接状态，见[连接中断](#页面已打开但连接中断)。
- 页面已打开、发送任务才失败：按错误进入[模型与凭据](/tutorials/deepseek-harness-model-provider/)；输入区不可用则进入[工作区排障](/errors/dsh-workspace-not-selected/)。

每次只修正一个已定位的问题，再[验证服务与原失败能力](#修复后怎样验证)。不要用重装、清空 Home 或结束全部 Node 进程代替定位。

## 安装卡住、ETARGET 与 pnpm 找不到：先确定失败阶段

2026-09-08 补充：先保存命令和第一条错误，按下表选择检查动作。终端还在下载 npm 包、Host 没启动、浏览器断线和模型任务失败，需要不同的证据。

| 失败阶段与症状 | 先做什么 | 怎样判断下一步 |
|---|---|---|
| `npx` 长时间没有启动地址 | 检查是否等待安装确认，记录最后一行 npm 输出；检查当前 registry 与目标版本元数据 | 元数据查询失败先检查网络与 registry；查询成功仍不代表依赖下载和启动成功 |
| `ETARGET` / `No matching version found` | 从错误复制完整包名和版本范围，查询该包，而不只查询 DSH 主包 | 区分包名或版本写错、当前 registry 未提供该版本；保留查询时间与返回结果 |
| `pnpm not found on PATH` | 在启动 DSH 的同一个终端执行 `pnpm --version`，检查可执行文件路径 | 没找到就按 pnpm 官方安装说明完成环境配置，再新开终端复查 |
| 已下载，但没有监听地址且进程退出 | 保存启动日志，核对 Node、DSH、端口与 Profile | 按本页对应错误进入精确排障，不先改浏览器 |
| 终端仍运行，浏览器打不开或断线 | 核对终端实际地址、访问机器及连接错误 | 浏览器连接问题与服务退出分开处理 |
| 页面能打开，发送任务后失败 | 保存任务错误码与 Provider 返回信息 | 凭据、模型路由或额度问题不能靠重装 Web UI 判断 |

### 只查询元数据，不先切镜像或清空缓存

以下命令不会安装 DSH。示例查询安装指南采用的固定版本；排查 `ETARGET` 时，应把第二条命令的包名和版本替换为错误中的实际值。

```bash
npm config get registry
npm view @deepseek-ai/dsh@0.2.0-rc.2 version
npm view @deepseek-ai/dsh@0.2.0-rc.2 version --registry=https://registry.npmjs.org/
```

第二条使用当前配置，第三条仅为这一次查询指定官方 registry，不修改全局配置。对比结果有助于定位 registry 差异，但不能凭一次失败断定镜像缺包，也不能凭主包存在断定全部依赖可安装。[npm view 官方说明](https://docs.npmjs.com/cli/v11/commands/npm-view/)

不要把“安装卡住”直接等同于缓存损坏，也不要用删除 DSH Home 或 Session 作为下载故障的首步。版本选择和回退前的数据处理见[更新与卸载指南](/tutorials/dsh-update-uninstall/)。

### pnpm 已安装，为什么 DSH 仍然找不到？

先在运行 DSH 的同一个终端执行 `pnpm --version`。macOS/Linux 用 `command -v pnpm` 查看路径；Windows PowerShell 用 `Get-Command pnpm`。系统中装过 pnpm 或 Corepack，并不能证明当前进程的 PATH 能找到 pnpm；完成安装或修改环境后，重新打开终端再检查。[pnpm 官方安装说明](https://pnpm.io/installation)

固定 `0.1.2-rc.1` 的插件管理源码通过子进程调用 `pnpm`；出现 `ENOENT` 时输出 `pnpm not found on PATH` 并返回 `127`。这与下载超时或 `allowBuilds` 拒绝构建是不同问题。[固定源码](https://github.com/deepseek-ai/deepseek-harness/blob/a66e4702047846cdaa10c66c9d3df3951f5ea70d/apps/cli/src/plugin.ts)

普通 npm 用户从[安装指南](/tutorials/deepseek-harness-install-web-ui/)启动；`pnpm install` 是在项目目录安装依赖的命令，不能脱离当前目录照抄源码开发流程。本节仅静态复核插件管理的 pnpm 调用，不表示已安装或运行第三方插件。

## 确认命令和运行时

本页历史基线的固定启动命令是 `npx @deepseek-ai/dsh@0.1.1-rc.2 web`，默认地址是 `http://127.0.0.1:3080`。`0.1.1-rc.2` 要求 Node.js `^22.19.0 || >=24.0.0`。确认当前终端实际调用的是预期 Node.js，而不是系统中另一个旧版本。完整五步路线见[DeepSeek Harness 安装与 Web UI 教程](/tutorials/deepseek-harness-install-web-ui/)。

## 排查端口和残留进程

如果日志提示端口被占用，先确认占用者是否是另一个仍在运行的 DSH 实例。不要为了释放端口批量结束不认识的系统进程。优先正常关闭旧实例，或使用 `--port` 选择另一个端口。跨平台只读检查命令和 Host 限制见[3080 端口占用修复](/errors/dsh-port-3080-in-use/)。

## 区分网络、权限和配置问题

下载依赖失败通常与网络、代理或证书有关；写入失败通常与目录权限或安全软件有关；启动后模型不可用则更可能是配置或凭据问题。一次只改变一个变量，并记录变化后的错误。

页面打开但输入框不可用时，先检查是否[选择了 Workspace](/errors/dsh-workspace-not-selected/)。启动后模型不可用时，按[模型与 Provider 配置](/tutorials/deepseek-harness-model-provider/)检查凭据和路由。

如果错误是 `SANDBOX_UNAVAILABLE`，表示受限模式没有可用的沙箱后端并已失败关闭。不要为了绕过错误直接使用完全访问权限；先按[DSH 权限与沙箱指南](/tutorials/dsh-permissions-sandbox/)确认平台后端与实际风险。

## 页面已打开，但连接中断

先确认原启动终端中的 DSH 服务是否仍在运行。服务已经退出、地址不对或端口冲突时，点击重连不会启动服务；先处理终端错误。页面仍与 Host 连接、只有模型请求出现 401 时，也应排查凭据而不是反复重连。

在 alpha.2 的展开侧边栏中，底部“设置”旁会显示异常后的连接状态：

| 可观察状态 | 含义与操作 |
|---|---|
| 连接异常 | 浏览器到 Host 的连接失败；确认服务和访问地址后，可使用立即重连 |
| 连接中 | 正在尝试恢复；悬停或键盘聚焦可显示立即重连操作 |
| 短暂显示连接成功 | 连接已恢复，随后提示消失；再用最小只读任务核对功能 |
| 没有指示 | 健康初次连接保持静默，侧栏收起也会影响显示；不能单凭没有提示判断服务正常 |

固定实现把手动入口连接到 `Connection.reconnect()`。它不是“修复全部网络问题”，更不是关闭认证或放开工作区权限的理由。[连接恢复官方说明](https://github.com/deepseek-ai/deepseek-harness/blob/0a53fb55bea101816fa226bb964ae2bed71c343b/packages/client/ui-settings-general/README.zh.md)

重连持续失败时记录服务状态、DSH 版本、操作系统、连接提示与脱敏错误。不要公开启动链接令牌、Cookie 或真实凭据；也不要先删除 Profile、Session 或禁用防火墙。想确认是否值得评估新入口，阅读[alpha.2 更新与适用范围](/tutorials/deepseek-harness-0-1-2-alpha-2/)；它没有自动替换 npm 默认安装版。

### alpha.3 只减少一种“误判断线”

本小节 alpha.3 专指 `0.1.2-alpha.3`，不是后续版本线的同名编号。

`0.1.2-alpha.3` 针对 Host 被同步工作短暂阻塞的情况调整了连接判断：网关容忍有限次心跳缺失并安排后续终止检查，客户端准备阶段超时会记录警告，而不是立即把停顿 Host 当作断开。这有助于减少“后端仍在工作，却被页面提前判定断线”的情况。[alpha.3 完整变化与适用范围](/tutorials/deepseek-harness-0-1-2-alpha-3/)

这不是全部连接故障的统一修复。服务进程已经退出、访问地址或端口错误、代理切断、认证令牌失效、模型 Provider 返回 401，以及网络确实不可达时，仍应按本页症状逐项排查。本站只完成固定源码审阅，没有运行 Host 停顿复现测试。

## 修复后怎样验证

重新执行一个最小、只读任务，确认界面、日志和输出范围都正常。如果问题仍然存在，把脱敏后的环境、命令、错误和已尝试步骤一起提交，而不是重复执行未经理解的修复脚本。

需要重新走完整流程时返回[安装 DeepSeek Harness 并启动 Web UI](/tutorials/deepseek-harness-install-web-ui/)；需要按其他故障阶段查找时进入[DeepSeek Harness 错误知识库](/errors/)。

## 0.1.6-alpha.2：启动错误与日志

2026-09-18 固定源码复核；本节只覆盖 alpha.2 的启动审计，不改变下方旧版本案例。新版区分启动失败的条目与等待依赖服务的条目，等待不等于该服务已崩溃。

| 终端或页面现象 | 判断与下一步 |
|---|---|
| 必需条目失败或未激活，启动退出 | 保存失败条目、依赖等待摘要和 `Full diagnostics` 指向的日志，检查最先失败的依赖 |
| 可选条目未激活，但页面可以打开 | 核对缺失能力及其依赖；可选失败不一定阻断整个 Host，首页可用不等于全部正常 |
| 日志明确为端口占用 | 按[3080 端口排障](/errors/dsh-port-3080-in-use/)处理，不重配模型 |
| 已启动但输入区不可用、模型认证失败或旧会话打不开 | 分别进入[Workspace](/errors/dsh-workspace-not-selected/)、[模型配置](/tutorials/deepseek-harness-model-provider/)或[会话排障](/errors/dsh-session-open-failed/) |

CLI 对 `StartupError` 写入实际 DSH Home 下的 `logs/startup-<ISO 时间，冒号替换为短横线>-<UUID>.log`，并在 stderr 显示 `Full diagnostics: <实际路径>`；先按终端路径找文件，不猜跨平台绝对目录。Home 可随 `DSH_HOME` 配置改变。日志无法写入时会提示写入失败，并把完整诊断输出到 stderr；其他普通错误不能一概套用这个文件位置。

报告包含 DSH/Node 版本、平台、Profile 和完整错误对象及其原因。启动器不主动采集环境值，但插件错误可能包含配置或凭据；分享前移除 Key、Token、私人路径和业务内容。实例占用先正常退出相应实例，不删除锁文件、清空 Home 或结束所有 Node 进程。修复后同时检查退出状态、页面和此前失败能力；发行说明中的等待改善没有本站速度实测数据。

依据：[启动审计](https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/boot/app-boot/README.zh.md)、[诊断日志实现](https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/apps/cli/src/startup-diagnostics.ts)。

## 0.1.5-rc.1：Windows 路径和断线恢复

[候选版发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1)列明 Windows 盘符根目录 Workspace 的分隔符、标题和绝对路径校验修复，以及 Web 断线后自动恢复修复。SDK Windows 启动修复是另一条路径，不能把 Web 页面断线统一归因于 SDK。

先记录实际版本和故障阶段：盘符根目录不能作为 Workspace 时核对路径与权限；页面断线时核对 Host 进程、地址和网络；SDK 崩溃时转[Headless 与 SDK 指南](/tutorials/dsh-headless-guide/)。不因新版有修复就删除旧 Profile 或会话。本站未运行这些平台复现，具体错误仍按前部症状表分流。

## 0.1.5-alpha.2：npm 安装触发 fs-ext 编译

[alpha.2 发行说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2)列明修复 npm 安装需要依赖 `fs-ext` 本地编译的问题。这是官方版本说明，本站未执行跨平台安装验收；不能推广为所有架构已无原生依赖问题。

| 错误阶段 | 先检查 | 不要混淆 |
|---|---|---|
| npm 安装时 fs-ext / 编译链失败 | 实际安装目标、包版本、平台和完整脱敏错误 | 磁盘装了新版不代表启动入口已更新 |
| 源码运行缺 system.node 等 addon | 源码提交、构建步骤与平台产物 | npm 安装修复不等于源码可跳过构建 |
| 程序启动但客户端模块 404 | Profile、客户端注册和面板接口 | 不是重复安装编译工具就能解决 |

需要评估 0.1.5-alpha.2 时先阅读[更新与回退指南](/tutorials/dsh-update-uninstall/)，此处修复仅指历史版本，本站当前基线与命令见维护页。不要在唯一环境上反复升级或删除缓存、配置和会话；有具体错误再按前部阶段表排查。

## 新版会话加载变慢，先区分性能与启动故障

2026-09-05 的默认 npm 版本为 `0.1.2-rc.1`；`0.1.3-alpha.1` 是另一条预发布线。官方说明 0.1.3-alpha.1 存在可能影响部分历史会话加载的性能回退。页面已经打开但旧会话载入缓慢，不等于端口启动失败，也不能据此判断 Session 正文丢失。

先记录实际 DSH 版本、会话是否能列出、能否打开、是否有格式或锁错误，再进入[Session v2 与读取边界](/tutorials/dsh-session-guide/)。alpha.1 的 read 打开也可能生成迁移文件，诊断应使用副本。遇到写入占用时先排查仍在运行的进程，不删除锁文件；格式错误时保留原文件，不清空缓存或 DSH Home。

本节只补充固定来源与官方已知问题，未运行故障复现。若需切换版本，阅读[更新回退指南](/tutorials/dsh-update-uninstall/)和[0.1.3-alpha.1 专题](/tutorials/deepseek-harness-0-1-3-alpha-1/)；0.1.1-rc.2 与 0.1.2-alpha.2～alpha.5 小节保留原有适用范围。

## 从 rc.2 或 alpha.3 升级 alpha.4 后立即失败

**历史范围：标题中的 rc.2 指 0.1.1-rc.2，alpha.3 / alpha.4 指 0.1.2-alpha.3 / 0.1.2-alpha.4；保留原标题供旧链接访问。**

如果同一台机器、同一 Profile 在 `0.1.1-rc.2` 或 `0.1.2-alpha.3` 能启动，切换到 `0.1.2-alpha.4` 后立即失败，这属于 0.1.2-alpha.5 官方修复范围中的已知升级症状。固定实现将原因定位到 `session_projcache` 跨磁盘版本读取：旧缓存可能被按新版本错误解释并阻止启动。`0.1.2-alpha.5` 增加 v3、v4 兼容读取，并允许无法安全解释的可丢弃投影记录先备份再冷重建。

请先记录实际 DSH 版本、完整第一条与最后一条错误、Profile 路径和 Session 列表快照，再保存原数据副本。不要因为看到“缓存”就手动删除整个 Session 或 DSH Home；投影缓存与权威 Session 正文是不同数据角色。alpha.5 也不能解释端口冲突、Node 不兼容、Provider 401、网络断线或第三方插件构建失败。

本站没有执行 0.1.2-alpha.4→0.1.2-alpha.5 的真实升级。准备在隔离副本评估时，先阅读[alpha.5 修复范围与升级检查表](/tutorials/deepseek-harness-0-1-2-alpha-5/)和[DSH 更新、回退与卸载指南](/tutorials/dsh-update-uninstall/)，不要把版本切换和数据清理同时进行。

## 原始来源

- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/packages/boot/app-boot/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/ddefc45fbc7f8e46dd73185e68295696d1297887/apps/cli/src/startup-diagnostics.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-alpha.2
- https://docs.npmjs.com/cli/v11/commands/npm-view/
- https://pnpm.io/installation
- https://github.com/deepseek-ai/deepseek-harness/blob/a66e4702047846cdaa10c66c9d3df3951f5ea70d/apps/cli/src/plugin.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.3-alpha.1
- https://github.com/deepseek-ai/deepseek-harness/blob/d347e703908d0406b7a7ef80e3a0e594d86b2215/packages/session/session-persistence-jsonl/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.2
- https://github.com/deepseek-ai/deepseek-harness/blob/0a53fb55bea101816fa226bb964ae2bed71c343b/packages/client/ui-settings-general/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/0a53fb55bea101816fa226bb964ae2bed71c343b/packages/client/ui-settings-general/src/client/SettingsRoot.tsx
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/package.json
- https://github.com/deepseek-ai/deepseek-harness/blob/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e/apps/cli/reference/README.zh.md
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.3
- https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/client/connection/src/client/connection.ts
- https://github.com/deepseek-ai/deepseek-harness/blob/dd6322d604e00eec1ba5e0c8541159906a21094a/packages/api/gateway/src/stream-server.ts
- https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.2-alpha.5
- https://github.com/deepseek-ai/deepseek-harness/blob/db6bdc3576c2d4e7c965e8e3ed0c2a731eed87f5/.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.zh.md