企业官网建设流程全解析

刚开始用 npm 版 dsh 时，我觉得自己找到了终身体系：一条npm install -g dsh-cli装完，终端里随手dsh init、dsh run，要看可视化就敲dsh web，浏览器里点一点，其余时间都在命令行里打转。直到某次系统 Node 升级后，dsh web 面板怎么都启不来，终端里挂着服务进程一挂就是一下午，我才动了彻底迁移的心思——换到 DSH 桌面版，断掉对所有间接依赖的念想。

这篇文章就是我整个迁移过程的记录。我会先讲清楚 npm 版 dsh 和 dsh web 到底卡在哪里，再按我实操的顺序，从安装、配置导入、项目搬迁到日常工作流切换，一步步写下来。文末还有我踩过的三个坑的完整排查过程。不管你是刚把 dsh 用起来的新手，还是已经维护了一大堆工作区的老用户，照着这个顺序走，应该能少走不少弯路。

1. 为什么非迁不可：npm 版 dsh 和 dsh web 的边界问题

1.1 命令行很好用，但可视化操作一直在补课

npm 版 dsh 的核心价值在命令行。初始化一个工作区用dsh init，执行任务用dsh run，改配置用dsh config set，这几个命令对经常跟终端打交道的人来说非常顺手。但它的短板也很明显：一旦涉及历史记录回看、多个任务并行编排、批量修改配置这类操作，命令行就开始别扭了。比如我想对比最近十次任务各自的输入输出参数，靠dsh history --limit 10翻终端输出，眼睛都要看花。

所以 npm 版 dsh 提供了一个配套方案，就是 dsh web。启动方式是在项目目录里执行dsh web --host 127.0.0.1 --port 8080，然后浏览器访问本地端口，得到一个可视化面板。这个面板能看任务列表、点按钮触发执行、查看日志，确实比纯命令行直观不少。

但这种"命令行工具 + 临时 Web 服务"的组合，天然带着一种拼凑感。dsh web 不是独立产品，它只是 npm 版 dsh 的子命令，所有功能都寄生在命令行工具启动的进程里。换句话说，每次要用可视化面板，都得先让终端开着，再记一个本地端口号，用完还得手动关。单人小项目还能忍，等手头管理的工作区多起来，这套流程就成了日常负担。

1.2 dsh web 的四个致命痛点

第一个痛点是环境寄生。dsh web 跑在系统 Node 环境上，它对 Node 版本有隐性要求。我踩到的那次就是在系统 Node 从某个版本升上去之后，dsh web启动时直接抛出一段兼容性警告，虽然偶尔还能启动，但面板里部分功能已经失效。这种"工具活着但功能残了一半"的状态，比直接崩溃更让人难受。

第二个痛点是终端永驻。每次用 dsh web，我都得把一个终端窗口专门让给它，不能关断。如果碰上远程开发机，还得靠 tmux 或者 nohup 挂着。更讨厌的是端口冲突，8080 被占就换 8081，端口一多，我自己都记不清哪个面板对应哪个项目。

第三个痛点是状态丢失。dsh web 的面板状态，比如当前选中的任务列表、日志滚动的位置、页面里的过滤条件，都存在内存里。重启 web 进程，全部清零。任务本身的结果 npm 版 dsh 会持久化，但"你看过哪些、筛到哪一步"这类交互状态，它真不负责。这导致每次打开面板都要重新点一遍。

第四个痛点是共享困难。dsh web 默认只绑 127.0.0.1，自己一个人看没问题。但想把面板临时分享给同组的人看，就得改绑定地址、考虑鉴权，这套配置下来比任务本身还耗时。我试过一次之后就再也不想折腾了。

1.3 桌面版的本质区别：从"命令"到"应用"

DSH 桌面版的最大区别，在于它把运行时直接封进了应用包里。系统里有没有 Node、Node 什么版本，桌面版一概不关心。它自己管理本地服务，不需要终端窗口常驻；面板状态落到应用数据目录，关掉再打开，上次的布局、选中项、筛选条件都在。

这不是单纯把 dsh web 套了个壳，而是把原先那个"临时起服务、用完就散"的模型，换成了"常驻应用、状态持久"的模型。命令行仍然保留，但它不再承担"我要用可视化所以必须挂一个终端"的职责。想清楚这一层，迁移的理由就成立了：我要告别的是 dsh web 的脆弱和 dsh 命令行的边界模糊，而不是告别 dsh 本身。

2. 迁移前的准备：盘清家底再动手

2.1 先导出 npm 版的配置快照

迁移第一步不是安装桌面版，而是把 npm 版 dsh 的现状完整盘一遍。我先执行了dsh config list，把当前所有配置项列出来。重点记录这五类信息：

• 服务端地址（endpoint）：工具连接的核心数据源地址。
• 认证信息（token）：访问控制用的令牌。
• 包镜像源（registry）：拉取脚本依赖时走的仓库地址。
• 默认工作区（defaultProject）：每次打开工具默认进入的项目。
• 网络代理设置（proxy）：在特定网络环境下才需要。

然后找到配置文件本体。在 Linux 和 macOS 上是~/.dsh/config.json，在 Windows 上是%USERPROFILE%\.dsh\config.json。我直接把这份 JSON 复制了一份出来，命名为dsh-config-backup.json。这一步非常重要，因为后续迁移配置时我会手动改字段名，改错了还有原始备份可以对比。

2.2 清点项目脚本和扩展依赖

光备份配置还不够。npm 版 dsh 的工作区里还积累了大量项目脚本和扩展，我列了一张迁移清单，逐项核对哪些要搬、哪些要重新生成。

这份清点除了确认"要搬什么"，还逼我提前发现了两个隐患。一是某些自定义脚本用了比较新的 Node API，桌面版内置运行时不一定支持；二是旧扩展插件是特定版本装的，直接复制大概率不兼容。与其等迁移后再排查，不如在清单阶段就标红。

2.3 制定迁移顺序：先建新桥，再拆旧桥

迁移最容易犯的错是"先卸载再安装"。正确顺序应该是：

1. 先下载 DSH 桌面版安装包，装好但不急着配置。
2. 用桌面版的导入向导做基础配置迁移，此时不对 npm 版做任何改动。
3. 把项目工作区复制到桌面版的数据目录，或者直接在桌面版中引用旧路径。
4. 跑通高频场景，确认稳定。
5. 保留 npm 版至少两周，确认不再需要时再卸载。

这个顺序的本质是让新旧两个版本并行存在一段时间。桌面版的数据目录和 npm 版的~/.dsh是完全隔离的，两者互不干扰，所以并行非常安全。我见过同事图省事，迁移第一天就npm uninstall -g dsh-cli，结果桌面版导入配置时发现字段映射有问题，旧工具已经没了，只能靠备份一点点恢复，非常耽误事。

3. 桌面版安装与首次启动：版本对齐是关键

3.1 下载安装与版本确认

DSH 桌面版提供了对应各主要桌面系统的安装包，下载时我特意对了安装包的校验哈希，防止下载到残缺文件。安装过程本身没有悬念，一路默认路径。装完以后，第一次打开应用，桌面上多了一个独立程序图标，命令行里不会出现新的全局命令——它和 npm 版的dsh命令不冲突，这也是桌面版架构上更干净的地方。

打开应用后，我第一件事是看"关于"页面里的版本号，确认桌面版的内置运行时版本。这个细节大多数人会忽略，但它直接决定了后续脚本能不能跑。下面会详细讲。

3.2 首次启动的导入向导：自动导入 vs 手动导入

首次启动，应用检测到我系统里存在旧的~/.dsh/config.json，弹出了导入向导。它给两个选项：自动导入和手动导入。

自动导入会读取旧配置，把基础字段搬过来，整个过程只要点几下确认。我试了一次，发现它只映射了服务端地址这类最表层的信息，像 registry、proxy 这种字段都没有正确落位。所以如果你和我一样，npm 版里配置项比较多，建议直接选手动导入：它会让你指定一个 JSON 文件，然后按新版的字段规则去解析。手动导入虽然麻烦，但每一条配置都会被完整带过来，而且会在导入后给出一份"未被识别字段"的报告，方便我针对性处理。

3.3 内置运行时版本与旧脚本的兼容性预检

导入配置之后，我打开桌面版自带的脚本控制台，执行了一条命令：

node -v

结果让我心里一沉：桌面版内置的是 Node 18 LTS，而我之前 npm 版 dsh 跑的系统 Node 是更新的大版本。这意味着我原来写的部分脚本，凡是用到新版本才有的 API，在桌面版里会因为找不到对应函数而直接失败。

我建议你在迁移时也执行同样的检查，然后提前做一个运行时探针脚本，把常用的判断、循环、异步操作都跑一遍。别等迁完项目才发现脚本全挂了，那会儿再回头找原因，排查成本会高很多。这一步做完了，才算真正做好安装层面的对齐。

4. 数据与配置迁移实操：从 ~/.dsh 到桌面版数据目录

4.1 配置文件字段差异与手动改写的完整过程

npm 版和桌面版的配置字段并不是一一对应的。我手动导入时，把旧的config.json与新版模板字段做了逐项比对，发现下面这些重命名：

老的 JSON 长这样：

{ "endpoint": "https://internal.example-dsh-server", "token": "dsh-token-xxxx", "registry": "https://npm.example-mirror", "defaultProject": "client-app", "proxy": "http://proxy.example:8080", "autoSave": true }

桌面版要求的导入格式是这样：

{ "serverUrl": "https://internal.example-dsh-server", "authToken": "dsh-token-xxxx", "packageRegistry": "https://npm.example-mirror", "workspacePath": "/Users/me/DSH-Workspace/client-app", "network": { "proxy": "http://proxy.example:8080" }, "editor": { "autoSave": true } }

在手动导入时，旧字段如果没改成新名字，导入器会直接丢弃，而不是猜测你是什么意思。这一点我觉得是个优点：它不会默默做错误映射。不过代价就是我得自己维护这张字段对照表。修改完再导入，桌面版设置的"配置概览"页里逐项核对，发现 serverUrl 和 authToken 都正确带入了，这才放心。

4.2 项目工作区的三种搬迁方式

工作区里的项目代码有几种搬法，我根据自己的实际使用场景做了取舍。

第一种是原地引用。如果项目本来就在稳定路径，比如/data/workspace/client-app，桌面版导入项目时直接选择该目录，不用复制任何文件。这种方式最省事，但前提是路径里不能有容易被误解析的符号。旧配置里如果写过~/dsh-workspace/client-app这种以波浪号开头的相对路径，导入后桌面版不会自动解析波浪号，会直接标记为路径不可用，需要改成完整绝对路径。

第二种是整体复制到应用数据目录。桌面版在 Linux 上是~/.config/DSH/，macOS 上是~/Library/Application Support/DSH/，Windows 上是%APPDATA%\DSH\。把整个项目目录复制过去，然后新建工作区并指向复制后的位置。好处是以后所有 dsh 相关数据都集中在一个地方，备份方便；坏处是复制大项目时比较耗时。

第三种是复制后同步。如果你和我一样，项目里同时有代码仓库和任务脚本，我会把代码仓库留在原地，把 scripts 目录复制进桌面版工作区，任务脚本的引用关系用桌面版的"导入脚本"功能重新建立。这样既保留了代码侧的 git 历史，又把任务执行相关的内容收敛到桌面版里。

4.3 缓存和日志：不值得搬，重新生成更快

旧目录里体积最大的通常是~/.dsh/cache，里面是各种依赖包和历史任务的临时数据。桌面版第一次运行时会自动创建同名缓存目录，我选择不搬旧缓存，而是让它重新拉取。原因很简单：缓存的产生依赖当时的依赖版本，跨版本直接复用，容易把不兼容的包带到新环境，排查起来反而更麻烦。

日志也是类似。旧日志就当历史归档，在~/.dsh/logs里留着不去动它。桌面版自己的日志在logs/main.log这类路径下，后续排错我主要看这个文件。这两类数据属于"生成物"，不值得花精力搬运。

5. 日常操作流水的脱胎换骨：命令对照与多窗口工作流

5.1 高频命令的桌面版对照表

刚切换到桌面版时，我最不习惯的是找不到原来的命令入口。下面这张对照表帮我度过了适应期：

这张表看起来像是"把命令换成了按钮"，但实际体验差别很大。拿dsh web来说，以前每次动手前都要想一遍"端口有没有被占、要不要挂后台"，现在这个心智负担整个消失了。应用启动，面板就在那里，不需要任何前置动作。

5.2 从"终端挂着长任务"到"任务面板托管"

npm 版时代跑长任务，我经常是开三个终端窗口：一个挂着任务进程，一个盯日志，一个备用。跑并行任务更是手忙脚乱，有时还得写 shell 脚本同时拉起多个dsh run。

桌面版的任务面板把"任务"变成了可观察的持久对象。我可以同时启动多个任务，每个任务独立显示进度、日志输出、退出码。任务失败后可以直接在面板里点重试，不用回到终端重新输入整条命令。更实用的是断点续跑，任务中途断了，面板里能从断点处继续，这个能力是纯命令行很难实现的。

我试过同时跑一个数据清洗任务和一个依赖更新任务，两个任务在面板里并行推进，各自日志互不干扰，鼠标点一下就能切换查看。这种体验用 npm 版配合 tmux 也能七七八八做到，但绝对没有桌面版这么顺滑。

5.3 协同时代的访问控制：彻底告别 dsh web 的手工配置

桌面版的协作能力是压垮旧方案的最后一块积木。应用设置里有一个"允许局域网访问"的开关，打开后会自动监听相应网络接口并生成一个访问地址。我只需要勾选，再配置一个访问令牌，同组同事就能在浏览器里打开这个地址，临时查看任务执行情况。

对比以前用 dsh web 共享面板的流程：改绑定地址、改防火墙、折腾鉴权、还得保持我这个终端不能关。现在这些全被桌面版接管了。基于主机的访问规则、令牌校验、会话管理都在设置页里完成。我当然不会把面板暴露到公网，但在受控的内网环境里，这个功能非常实用。

6. 迁移路上踩过的坑：完整的排错链路

6.1 坑一：导入后提示项目路径不存在

迁移后第一次打开工作区，我就看到项目卡片上显示"路径不可用"。直觉告诉我先看日志，打开logs/main.log，里面有一条清晰得有点过分的错误提示：project path not found: ~/dsh-workspace/client-app。

问题就出在这个波浪号上。旧配置里我用的是~/dsh-workspace/client-app这种相对写法，npm 版 dsh 在启动时会自动展开用户目录，所以一直没问题。桌面版没有做这层展开，它需要的是绝对路径/Users/me/dsh-workspace/client-app。

修复很直接：在桌面版的项目设置里把路径改写成完整绝对路径，应用立刻识别到了项目。这个坑给我的教训是：迁移工具会保守地保留旧值，但它不会替你完成"智能路径解析"。任何历史配置里用了环境变量、波浪号、相对路径的，导入前都该统一改成绝对路径。

6.2 坑二：旧配置字段未映射导致连接反复 401

项目路径的问题解决后，我又碰到连接数据源时一直报 401 未授权。这个坑比前一个隐蔽。日志里的请求记录显示 token 没有出现在请求头里，但我在配置概览里明明看到了 authToken 字段有值。

层层排查后才发现，问题出在导入时我对字段映射的理解有偏差。自动导入那次只把 endpoint 映射成了 serverUrl，token 还是旧的token，而桌面版解析认证用的是authToken，旧字段自动导入时被悄悄丢弃了。后来我手动导入时虽然改了大部分字段名，但 token 这一项写成了嵌套结构，导致没被读进认证模块。

最后我在手动导入的 JSON 里把认证字段单独提出来，确认顶层的authToken有值，重新导入后才恢复正常。这个坑让我养成了坏毛病：每次导入完，第一件事不是开心地开始用，而是把配置概览里的每一项和旧配置逐条 diff 一遍。

6.3 坑三：内置 Node 18 与新 API 不兼容

第三个坑是运行时版本问题在真实任务中爆发。我有个任务脚本用了较新版本 Node 才提供的Array.fromAsync方法，在旧 npm 版环境里跑得好好的，迁到桌面版后一执行就报Array.fromAsync is not a function。

当时第一反应是脚本依赖没装全，还跑去改了一通依赖。直到打开桌面版内置控制台执行node -v，看到输出 Node 18，才把问题定位到运行时版本上。后面我检查项目里所有脚本，凡是用到较新语法特性的地方都做了改造，统一改成用Promise.all加循环的写法，这样在旧运行时上也能稳定跑。

如果你不想改脚本，桌面版的扩展设置里也有"运行时兼容模式"选项，可以降低部分 API 的启用门槛，但兼容模式终归不如直接修脚本干净。迁移前先跑探针脚本，把版本兼容性问题提前暴露，比等任务失败后逐行排查要高效得多。

6.4 迁移一半时怎么安全回滚：保留并观察两周

迁移过程中我还碰到过一次想回滚的情况，就是 6.2 那个 401 问题，一度以为配置全丢了，想退回 npm 版。后来确认是因为桌面版数据目录和 npm 版完全隔离，旧配置没有被改动，才静下心继续排查。

所以我的建议非常明确：桌面版稳定运行至少两周之前，千万不要卸载 npm 版。你可以继续留着~/.dsh目录，甚至继续用dsh命令做高频操作，让桌面版作为日常入口。等新工作流完全跑顺了，再把 npm 版卸载，然后把~/.dsh归档，而不是直接删掉。归档比删除多一层保险，万一某个历史脚本还要从旧配置里找线索，你还有地方翻。

迁移这件事，表面上是把配置和项目从一个工具搬到另一个工具，实际做下来，更像是一次工作流梳理。我趁这次机会整理了一直没理清的脚本依赖，淘汰了几个不再需要的扩展，还统一了路径规范。桌面版带来的体验提升也很直接：关掉应用再打开，面板还是上一次的样子，日志位置没丢，任务状态还在；这种"状态持久"的踏实感，是 npm 版加 dsh web 给不了的。

最后分享一个小技巧：桌面版的数据目录值得纳入你的日常备份方案。我直接把~/.config/DSH加进了定时备份任务，这样无论应用本身怎么升级、系统怎么重装，只需要指定备份目录里的配置文件，再重新导入一次工作区路径，整套环境就回来了。折腾一次迁移不容易，后续的备份机制别省。