code-server Changelog 深度解读：版本规范、关键能力演进与安全修复路线

本文基于 code-server 仓库根目录的 CHANGELOG.md 展开，讲清三件事：code-server 的版本号体系与变更记录格式如何解读、从 4.x 各版本中沉淀出的重要 CLI 参数与环境变量（如 --cookie-suffix、--i18n、--skip-auth-preflight 等）及其源码级实现依据，以及贯穿版本历史的安全修复脉络。读完后，你可以把 Changelog 当作一份"参数考古手册"和"安全升级检查清单"来使用，快速定位某个能力自哪个版本引入、某次安全修复对应哪段源码。

Changelog 的格式规范与版本号体系

CHANGELOG.md 开篇声明了该文件的编写约定：

• 格式基于 Keep a Changelog 规范，每个版本按 Changed / Added / Deprecated / Removed / Fixed / Security 分类；
• 项目遵循语义化版本（Semantic Versioning）。

文件头部还保留了一段 HTML 注释形式的条目模板（## [9.99.999] - 9090-09-09，下分 Changed / Added / Deprecated / Removed / Fixed / Security 六小节），用于指导维护者按统一结构追加新条目。

code-server 的版本号与上游 VS Code（仓库内称为 Code）版本号强绑定。每个条目都形如：

## [4.133.0] - 2026-08-17
Code v1.133.0
### Changed
- Update to Code 1.133.0

从源码结构看，这种"4.x.y 对应 Code 1.x.y"的映射意味着：升级 code-server 的次版本号，基本等价于同步一次上游 VS Code 版本。当前仓库最新已发布条目为 4.133.0（2026-08-17），其上方留有空的 ## Unreleased 段，即下一个版本的待发布区。

一个值得注意的细节是条目之间并非完全机械：例如 4.113.1 的条目正文解释了它是一次"重发布"（re-release）——因为 CI 重构失误导致 arm64 与 armv7l 的独立发布包错误打包了 amd64 的 Node 二进制，该条目本身就是一种"修复说明"。这说明 Changelog 除了逐条罗列改动，还承担了发布质量追溯的作用。

从 Changelog 中还原参数演进史：四个典型能力

Changelog 是定位"某参数自哪个版本可用"的最佳索引。下面选取四个在版本记录中首次出现的代表性能力，并结合当前仓库源码给出实现印证。

--cookie-suffix：避免多实例 Cookie 冲突

4.107.0（2026-12-17）新增 --cookie-suffix 标志，用于在使用内置密码认证时给会话 Cookie 追加后缀，从而避免同一根域下多个 code-server 实例的 Cookie 相互覆盖。

当前源码中该能力的落点是 src/common/http.ts 的 getCookieSessionName 函数：

export function getCookieSessionName(suffix?: string): string {
  return suffix ? `code-server-session-${suffix.replace(/[^a-zA-Z0-9-]/g, "-")}` : "code-server-session"
}

可以看到 Cookie 名最终形如 code-server-session-<suffix>，且后缀中的非法字符（除字母、数字、连字符外）会被统一替换为 -。src/node/cli.ts 中还记录该参数可通过环境变量 CODE_SERVER_COOKIE_SUFFIX 等价设置（见 src/node/cli.ts 的默认值注入逻辑）。

--app-name 与 CODE_SERVER_APP_NAME：品牌化部署

--app-name 的影响范围在多个版本中逐步扩大：

• 4.12.0：应用到 PWA 标题；
• 4.111.0：影响错误页标题；
• 4.122.0：影响编辑器窗口标题（作为标题模板中 ${appName} 的取值）与 Help > About 对话框，并新增 CODE_SERVER_APP_NAME 环境变量。

源码印证见 src/node/cli.ts（默认值 args["app-name"] ??= process.env.CODE_SERVER_APP_NAME || "code-server"）、src/node/routes/errors.ts（错误页模板替换 {{APP_NAME}}）以及 src/node/routes/login.ts（登录页欢迎文案按 app 名称插值）。

--i18n：自定义界面字符串

4.102.0（2025-07-16）新增 --i18n 标志，指向一个 JSON 文件用于翻译或自定义界面字符串，可与 --locale 组合使用。原始键集合可在 src/node/i18n/locales/en.json 中查看；仓库内已内置 ja、zh-cn、th、ur 等语言文件（位于 src/node/i18n/locales）。src/node/cli.ts 对其的描述为"与默认字符串合并、支持所有 i18n 键"。

--stdin-to-clipboard：集成终端里的剪贴板桥

4.90.0（2024-06-11）新增 code-server --stdin-to-clipboard（短选项 -c），用于把 stdin 内容写入浏览器端剪贴板。Changelog 中给出的用法示例可直接复制：

alias xclip="code-server --stdin-to-clipboard"
echo -n "hello world" | xclip

这是远程编辑场景中打通"服务器终端 → 浏览器剪贴板"的关键小工具，适合在远端 shell 中直接复用 xclip 习惯。

代理体系的关键版本节点

code-server 的端口转发（domain/path proxy）是 Changelog 中出现频率最高的主题之一，几个关键节点：

版本	日期	变更
4.8.0	2022-10-24	支持 Ports 面板，利用内置代理并读取 VSCODE_PROXY_URI（{{port}} 会被替换），如 VSCODE_PROXY_URI=https://{{port}}.kyle.dev 会把 localhost:3000 转发到 https://3000.kyle.dev
4.12.0	2023-04-21	设置 --proxy-domain 后，Ports 面板改用域名代理替代默认的路径代理
4.16.0	2023-07-28	新增 --disable-proxy 关闭 domain/path 代理路由；Code 侧的端口面板需另用 remote.autoForwardPorts=false 关闭
4.93.1	2024-09-23	新增 --abs-proxy-base-path，用于 code-server 不在根路径部署的场景
4.99.3	2025-04-17	新增 --skip-auth-preflight，让预检（OPTIONS）请求无需认证即可通过代理

当前源码中这些能力一一对应：--disable-proxy 的判定在 src/node/http.ts；--skip-auth-preflight 在 domain 与 path 两条代理路由中被消费，见 src/node/routes/domainProxy.ts 与 src/node/routes/pathProxy.ts；--abs-proxy-base-path 作为 proxyBasePath 注入路由，见 src/node/routes/index.ts。

安全修复脉络：从 Changelog 看升级优先级

Changelog 中 ### Security 小节是判断"是否必须升级"的最强信号。当前文件记录的安全条目（按时间倒序）：

1. 4.124.2（2026-06-16）会话 Cookie 泄漏到本地端口：使用内置密码认证时，会话 Cookie 会被转发到用户代理的本地端口；若该端口上的服务不可信，理论上可拿 Cookie 登录 code-server 并以用户身份执行命令。修复方式是代理前剥离 code-server 的会话 Cookie。对应的当前实现在 src/node/proxy.ts：proxy.on("proxyReq") 钩子中按 getCookieSessionName 定位会话 Cookie 并置空后重写 Cookie 头。
2. 4.99.4（2025-05-02）路径代理端口校验：强制路径代理中的端口为数字，防止代理到任意域名。
3. 4.14.1（2023-06-26）Node 二进制多余写权限：linux-amd64 tarball 中 Node 二进制带多余写权限，若解压时未设置 umask 可能导致二进制可被篡改。
4. 4.10.1（2023-03-04）WebSocket 源检查：为旧浏览器（不支持 SameSite Cookie）及同根域子域间的跨站劫持风险增加 origin 校验；使用反向代理时必须正确转发 Host 头，否则 WebSocket 会被拦截。
5. 4.5.2（2022-08-15）代理路由缺失认证：此前通过 my.domain/proxy/8000/ 可未认证访问本机 8000 端口的服务，影响"开启内置密码认证且本机跑未保护 HTTP 服务"的部署，官方明确建议此类用户立即升级。
6. 4.0.1（2022-01-04）XSS 修复：错误页对消息做 HTML 转义。

配套的 4.132.0（2026-08-10）Fixed 条目则说明了上述安全修复的后续打磨：代理时 Cookie 曾被解码再编码，可能与目标应用的编码方式不一致，现在改为除剥离会话令牌外"原样透传"。这与 src/node/proxy.ts 中 decode: identity / encode: identity 的注释（"编码解码均为空操作，只为在不改变其他 Cookie 的前提下移除令牌"）完全吻合。

行为变更与破坏性变更：升级前必读的条目

Changelog 中还散落着若干对运维有实际影响的变更：

• 4.92.2（2024-08-19）破坏性变更：移除了将编译目标从 es2022 改到 es2020 的补丁（该补丁与 VS Code 新版静态属性用法不兼容），可能影响更旧的浏览器，需升级浏览器或停留在旧版 code-server。
• 4.123.0（2026-06-03）：微软停止支持 armhf 远程，此版本起不再提供 armhf 构建。
• 4.114.1（2026-04-06）：改为从源码构建原生模块以匹配正确 glibc 版本，将 glibc 最低要求从 2.34 降回 2.28。
• 4.100.0（2025-05-12）：可信任域名支持运行时配置（--link-protection-trusted-domains 或 product.json 中的 linkProtectionTrustedDomains）；同时彻底禁用扩展签名校验（此前只是默认跳过，后来被报告会导致扩展无法安装）。
• 4.10.0（2023-02-15）：移除已弃废逾 13 个月的 --link 参数。
• 4.0.1（2022-01-04）架构级变更：code-server 迁移到上游新开源的 server 实现之上，OpenVSX 成为默认扩展市场，SERVICE_URL / ITEM_URL 被统一的 EXTENSIONS_GALLERY 变量取代，并移除 --extra-extensions-dir、--extra-builtin-extensions-dir、--install-source 等参数。
• 4.23.0 前后（2024-04）：条目版本号出现 4.23.x 与 Code 1.88.x 的对应，可见早期条目间曾存在编号断层，解读旧条目时应以"条目内标注的 Code 版本"为准，而非仅看 code-server 自身编号。

此外，4.6.0（2022-08-17）为 WebSocket 增加了心跳，防止 NGINX 等反向代理以默认 60 秒超时切断空闲连接。当前仓库中该机制由 src/node/heart.ts 的 Heart 类承担，以 60 秒间隔的活跃检测维持连接状态；4.4.0 的条目还提到 Heart.beat() 曾被重构为 async 以便测试，可参见 test/unit/node/heart.test.ts。

如何用这份 Changelog 做版本决策

结合以上解读，可以形成一套实用的使用方法：

1. 查能力可用性：按参数名（如 --cookie-suffix、--abs-proxy-base-path）在 CHANGELOG.md 中搜索，即可确定最低版本要求；当前参数的权威定义与帮助文本见 src/node/cli.ts（所有 CLI 标志均"直接映射"为配置文件键，见 src/node/cli.ts 中 --config 的描述）。
2. 查安全升级：只关注 ### Security 小节，命中"代理未认证""会话 Cookie 泄漏""二进制写权限"等条目的版本应视为强制升级点。
3. 查环境限制：armhf 支持（4.123.0 起移除）、glibc 版本要求（4.17.0 / 4.114.1）、编译目标（4.92.2）等条目决定了发布镜像的适用边界。
4. 配合仓库内文档：升级与安装相关的说明可继续参考 docs/upgrade.md、docs/install.md 与 docs/requirements.md。

Changelog 的最后一节说明该文件自 3.10.0 开始维护，更早版本的变更未记录于此。3.11.0、3.11.1 两个条目也标注了"Undocumented"，提示历史细节的完整程度因时期而异——对 4.x 时代（即 4.0.1 重新架构之后）的条目，其记录密度和可追溯性最高，也是本文各源码印证所覆盖的范围。