VSCode Remote-SSH离线部署与Stable-commit-id插件staging后缀问题修复

最近折腾了一台完全离线的内网服务器，打算用 VSCode 的 Remote-SSH 做远程开发。环境装完，插件也装好了，结果发现一个特别闹心的问题：每次保存文件时，文件名后面都会被追加一个 staging 后缀，比如 report_final_20250418.py 变成了 report_final_20250418-staging.py。一开始以为是自己手滑改了哪里，后来排查了一圈才发现，罪魁祸首是 Stable-commit-id 这款插件。它检测到 git 暂存区里有未提交的改动，就把 commit id 后面的状态标记成了 staging，连带着文件名里的版本号也被污染了。

这篇博文就围绕这个场景，把 VSCode SSH 离线部署的全流程、Stable-commit-id 插件的运行机制，以及这个 staging 后缀问题的完整排查与修复过程，一次性讲清楚。不管你是第一次搞离线开发环境，还是已经在用 Remote-SSH 但被各种奇怪问题折磨，这篇文章应该都能帮上忙。

1. 整体设计与思路拆解

1.1 离线部署为什么首选 VSCode + Remote-SSH

离线环境的痛点是显而易见的：不能随意下载依赖、没有插件市场、网络受限。很多团队会选择在服务器上装完整的 IDE（比如 PyCharm 专业版），但许可证、体积、配置成本都不小。相比之下，VSCode 的 Remote-SSH 方案的优势在于：本地只是壳，真正的代码、运行环境、插件都跑在远程服务器上。本地只需要一个编辑界面，服务器的 CPU、内存、文件系统、git 仓库全都不需要同步到本地。

这个架构对离线的意义在于：

• 本地只负责 UI 渲染和输入转发，不涉及重型依赖。
• 远程服务器的 Python 解释器、Node 环境、编译工具链，与本地完全隔离，不需要在本地重复安装。
• 插件可以在本地下载好 .vsix 包，再转移到离线服务器上手动安装，绕开插件市场不可达的问题。
• 代码文件、git 操作全部发生在服务器本地，没有同步冲突。

所以，离线部署的合理路径是：本地准备一切能准备的东西（VSCode 安装包、Remote-SSH 插件、服务器端离线插件包），然后通过 SSH 让两端建立连接，最后在服务器上完成全部开发工作。

1.2 这个项目里真正要解决的核心矛盾

再看这个标题里最刺眼的那个点：Stable-commit-id 插件的 staging 后缀。这个问题的本质不是一个单纯的“插件 Bug”，而是插件设计逻辑与用户实际工作流之间的冲突。Stable-commit-id 的设计初衷是在代码中插入当前 git 提交的 commit id，用于追踪每个文件对应的代码版本。它默认定义了一种状态机：

• 工作区干净，且没有暂存区改动：显示 [commit-id]
• 工作区有已暂存（staged）但尚未提交的改动：显示 [commit-id-staging]
• 工作区有未暂存的改动：显示 [commit-id-dirty]

问题是，它还会把这个 commit id 应用到你配置的导出文件名模板里。如果你在配置项里写的是 {filename}_{commit_id}.{ext}，那么在有 staging 改动时，生成的文件名就会变成 {filename}_{commit_id}-staging.{ext}。对于依赖稳定文件名做后续处理的流程（比如模型导出、固件生成、报告输出），这就会导致版本文件命名不统一，甚至被下游脚本识别为不同文件。

所以，真正要解决的核心矛盾是：如何保证离线环境中插件的版本标记功能可用，同时又不因为 staging 状态破坏文件名稳定性。

1.3 方案选型：改配置、改源码还是改习惯

面对这个 staging 后缀，我当时列了三个方案：

我最终选择了“修改插件源码 + 重新打包”的路线。原因是：团队里有人习惯改完代码先 git add 攒着，等一个功能完整了再 commit，这个流程本身没有问题，错的是插件不分场景一刀切地加 staging 后缀。与其让人改变工作习惯，不如让工具适配人。

2. 前置环境准备与离线部署实操

2.1 服务端 SSH 环境准备

离线服务器的 SSH 服务是 Remote-SSH 连接的基础。大多数 Linux 发