code-server 4.143.1 配置参数详解

目标：把 code-server 4.143.1 的 config.yaml 全部配置项、环境变量映射和优先级讲清楚，并用 12 组实测说明“为什么改了配置却不生效”。本文基于 2026-10-27 的 4.143.1 二进制实跑，回显照抄；部署形态见站内部署篇，命令行用法见本专栏下一篇。

一、环境信息

项目	实测值
版本	code-server 4.143.1（commit `22ddf60d`，捆绑 VS Code 1.143.1）
操作系统	Ubuntu 22.04.5 LTS（x86_64）
运行用户	root（`/root/.config/code-server/config.yaml`）
配置文件默认路径	`~/.config/code-server/config.yaml`
数据目录默认路径	`~/.local/share/code-server`
扩展目录默认路径	`~/.local/share/code-server/extensions`
默认监听	`127.0.0.1:8080`（首次启动写入配置文件）
认证默认值	`password`
实测端口	8140–8151（避开已占用端口）
参考日期	2026-10-27

二、配置文件在哪、怎么加载

2.1 默认路径

# root 用户
/root/.config/code-server/config.yaml

# 普通用户
~/.config/code-server/config.yaml

首次执行任意 code-server 命令时自动生成（不存在才写，不覆盖已有文件）：

[2026-10-27T10:19:33.895Z] info  Wrote default config file to /root/.config/code-server/config.yaml

初始内容只有四项：

bind-addr: 127.0.0.1:8080
auth: password
password: f0e73cf5113be6fc92827109
cert: false

2.2 指定其他配置文件

三条路径，优先级从高到低：

方式	写法	实测日志
命令行 `--config`	`code-server --config /etc/code-server/config.yaml`	`Using config file /etc/code-server/config.yaml`
环境变量 `CODE_SERVER_CONFIG`	`CODE_SERVER_CONFIG=/etc/code-server/config.yaml code-server`	`Using config file /etc/code-server/config.yaml`
默认路径	不传	`Using config file /root/.config/code-server/config.yaml`

两者同时存在时命令行优先，实测：

CODE_SERVER_CONFIG=/tmp/cs4/config.yaml \
  code-server --config /tmp/cs4/configB.yaml \
  --user-data-dir /tmp/cs4/udB

[2026-10-27T12:02:12.086Z] info  Using config file /tmp/cs4/configB.yaml
[2026-10-27T12:02:12.086Z] info  HTTP server listening on http://127.0.0.1:8146/

2.3 配置键与命令行参数一一对应

config.yaml 里的键就是命令行长参数去掉 --。例如：

bind-addr: 0.0.0.0:8080
disable-telemetry: true
trusted-origins:
  - https://ide.example.com

等价于：

code-server --bind-addr 0.0.0.0:8080 --disable-telemetry \
  --trusted-origins https://ide.example.com

布尔项写 true 即开启；数组项用 YAML 列表；字符串项写字符串。键名写错不会“静默忽略”，而是直接启动失败：

not-a-real-key: true

[2026-10-27T12:02:40.577Z] error error reading /tmp/cs4/badkey.yaml: Unknown option --not-a-real-key
exit=1

三、优先级：命令行 > 环境变量 > config.yaml

3.1 总原则

同一项在三个来源都出现时：

命令行（--flag）最优先；
环境变量次之；
config.yaml 最后。

源码里的合并方式是先取配置文件、再用命令行覆盖（Object.assign({}, configArgs, cliArgs)），随后环境变量再做一轮覆盖。少数“只允许环境变量/配置文件”的敏感项例外：password、hashed-password、github-auth 不允许出现在命令行，写了会直接报错：

code-server --password test123

[2026-10-27T11:57:25.111Z] error --password can only be set in the config file or passed in via $PASSWORD
exit=1

3.2 监听地址的优先级细节

bind-addr 不是简单的一层覆盖，实际顺序是：

默认 localhost:8080
  → config.yaml 的 bind-addr
  → 命令行 --bind-addr
  → 环境变量 CODE_SERVER_HOST（只改 host）
  → 命令行 --host（隐藏参数，只改 host）
  → 环境变量 PORT（只改 port）
  → 命令行 --port（隐藏参数，只改 port）

因此 PORT 会覆盖 --bind-addr 里的端口，只有显式 --port 能再压过 PORT。实测见 5.4。

3.3 密码来源优先级

HASHED_PASSWORD > PASSWORD > config.yaml 的 password。HASHED_PASSWORD 存在时日志会明确写：

- Using password from $HASHED_PASSWORD

而不是 $PASSWORD 或配置文件。实测见 5.2、5.3。

四、config.yaml 全项清单

说明：类型按 4.143.1 源码的解析规则标注；“仅命令行”表示写进配置文件没有实际意义；“隐藏”表示 --help 不展示但仍可解析。

4.1 监听、配置与认证

键	类型	作用	默认/备注
`config`	string	指定配置文件路径	仅命令行有意义；等价 `--config`
`bind-addr`	string	监听地址，格式 `host:port`	默认 `127.0.0.1:8080`；只写 host 时端口按 80
`host`	string	仅监听主机（隐藏，已废弃）	由 `bind-addr` 取代
`port`	number	仅监听端口（隐藏，已废弃）	由 `bind-addr` 取代
`socket`	string	监听 Unix socket 路径	设置后忽略 `bind-addr`
`socket-fd`	number	使用已预绑定的监听 fd	systemd socket 激活场景
`socket-mode`	string	Unix socket 文件权限	如 `0660`
`auth`	string	认证方式	`password` / `none`，默认 `password`
`password`	string	明文登录密码	只能写在配置文件或用 `PASSWORD`
`hashed-password`	string	Argon2 哈希密码	只能写在配置文件或用 `HASHED_PASSWORD`；优先于 `password`
`cert`	string/boolean	证书路径；写 `true` 生成自签证书	默认 `false`
`cert-host`	string	自签证书的 CN/主机名	`--cert` 无路径时使用
`cert-key`	string	证书私钥路径	使用自有证书时必须提供
`trusted-origins`	string[]	跳过 Origin 校验的可信来源	反代域名与访问域名不一致时用

4.2 安全与访问控制

键	类型	作用	默认/备注
`cookie-suffix`	string	给会话 Cookie 加后缀	避免同域多实例 Cookie 冲突；也可用 `CODE_SERVER_COOKIE_SUFFIX`
`disable-file-downloads`	boolean	禁止从编辑器下载文件	也可用 `CS_DISABLE_FILE_DOWNLOADS=true/1`
`disable-file-uploads`	boolean	禁止上传文件	只能配置文件或命令行
`disable-workspace-trust`	boolean	关闭工作区信任提示	仅影响当前会话
`disable-proxy`	boolean	关闭域名/路径代理路由	也可用 `CS_DISABLE_PROXY=true/1`
`skip-auth-preflight`	boolean	允许未认证的预检请求通过代理	一般无需开启
`link-protection-trusted-domains`	string[]	可信域名链接免二次确认	可重复传入多个域名
`github-auth`	string	GitHub Token	只能配置文件或 `GITHUB_TOKEN`
`enable`	string[]	实验特性开关（隐藏）	4.143.1 无实际实验项

4.3 数据目录与扩展

键	类型	作用	默认/备注
`user-data-dir`	string	用户数据目录	默认 `~/.local/share/code-server`
`extensions-dir`	string	扩展目录	默认 `<user-data-dir>/extensions`
`builtin-extensions-dir`	string	内置扩展目录（隐藏）	一般不改
`install-extension`	string[]	安装扩展，`publisher.name[@version]` 或 vsix 路径	可重复传多个
`uninstall-extension`	string[]	卸载扩展	可重复传多个
`list-extensions`	boolean	列出已安装扩展	常与 `--show-versions` 连用
`show-versions`	boolean	列表显示版本号	仅对 `--list-extensions` 有意义
`force`	boolean	安装/卸载时不交互	脚本化必备
`locate-extension`	string[]	打印扩展安装路径（隐藏）	排障用
`category`	string	扩展分类过滤（隐藏）	列表场景使用
`enable-proposed-api`	string[]	为指定扩展启用 proposed API	可传扩展 ID
`enable-remote-storage`	boolean	工作台存储放服务端而非浏览器	多设备一致时有用

4.4 网络、代理与子路径

键	类型	作用	默认/备注
`proxy-domain`	string[]	端口转发使用的域名	支持 `{{port}}` 模板；可重复
`abs-proxy-base-path`	string	绝对代理请求的统一前缀	子路径反代时配合使用
`skip-auth-preflight`	boolean	预检请求免认证	见 4.2
`disable-proxy`	boolean	关闭代理路由	见 4.2

4.5 运行、日志与界面

键	类型	作用	默认/备注
`disable-telemetry`	boolean	关闭遥测	建议生产开启
`disable-update-check`	boolean	关闭每 6 小时的版本检查	内网环境建议开启
`disable-getting-started-override`	boolean	关闭 Help: Getting Started 的 coder 覆盖页	也可用 `CS_DISABLE_GETTING_STARTED_OVERRIDE=true/1`
`locale`	string	界面与登录页语言	如 `zh-cn`、`en`
`open`	boolean	启动时打开本地浏览器	远程环境无效
`log`	string	日志级别（隐藏）	`trace`/`debug`/`info`/`warn`/`error`
`verbose`	boolean	等价 `--log trace`	排障时临时开
`app-name`	string	替换标题栏与欢迎语里的 `{{app}}`	默认 `code-server`；也可用 `CODE_SERVER_APP_NAME`
`welcome-text`	string	登录页文案（已废弃）	新版本用 `app-name`/`i18n`
`i18n`	string	自定义翻译 JSON 路径	与默认文案合并
`idle-timeout-seconds`	number	空闲多少秒后关闭服务	必须大于 60；也可用 `CODE_SERVER_IDLE_TIMEOUT_SECONDS`
`reconnection-grace-time`	string	客户端断线重连宽限秒数	默认 10800（3 小时）；也可用 `CODE_SERVER_RECONNECTION_GRACE_TIME`
`vscode-option`	string[]	透传给 VS Code 服务端的参数	可重复；也可用空格分隔的 `VSCODE_OPTIONS`
`session-socket`	string	会话 IPC socket 路径（隐藏）	默认 `<user-data-dir>/code-server-ipc.sock`
`help`	boolean	显示帮助（仅命令行）	等价 `-h`
`version`	boolean	显示版本（仅命令行）	等价 `-v`
`json`	boolean	JSON 输出（隐藏，仅命令行）	脚本化用
`ignore-last-opened`	boolean	忽略上次打开目录（仅命令行）	等价 `-e`
`new-window`	boolean	强制新窗口（仅命令行）	等价 `-n`
`reuse-window`	boolean	复用已有窗口（仅命令行）	等价 `-r`

五、环境变量映射与 12 组实测

5.1 环境变量映射表

环境变量	映射到	说明
`PASSWORD`	`password`	明文密码，优先于配置文件
`HASHED_PASSWORD`	`hashed-password`	Argon2 哈希，优先于 `PASSWORD`
`GITHUB_TOKEN`	`github-auth`	GitHub Token
`PORT`	监听端口	覆盖 `bind-addr` 的端口；显式 `--port` 可再覆盖
`CODE_SERVER_HOST`	监听主机	覆盖 `bind-addr` 的 host
`CODE_SERVER_CONFIG`	配置文件路径	`--config` 优先
`CODE_SERVER_COOKIE_SUFFIX`	`cookie-suffix`	同域多实例隔离 Cookie
`CODE_SERVER_RECONNECTION_GRACE_TIME`	`reconnection-grace-time`	断线重连宽限
`CODE_SERVER_IDLE_TIMEOUT_SECONDS`	`idle-timeout-seconds`	必须 > 60，否则启动失败
`CODE_SERVER_APP_NAME`	`app-name`	标题与欢迎语
`CS_DISABLE_FILE_DOWNLOADS`	`disable-file-downloads`	仅识别 `true` / `1`
`CS_DISABLE_GETTING_STARTED_OVERRIDE`	`disable-getting-started-override`	仅识别 `true` / `1`
`CS_DISABLE_PROXY`	`disable-proxy`	仅识别 `true` / `1`
`VSCODE_OPTIONS`	`vscode-option`	空格分隔，追加而不是替换
`LOG_LEVEL`	`log`	合法值 `trace`/`debug`/`info`/`warn`/`error`

5.2 实测一：CLI 覆盖 config.yaml 的监听地址

配置文件：

bind-addr: 127.0.0.1:8140
auth: password
password: fromconfig
cert: false
disable-telemetry: true

启动：

code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud1 --extensions-dir /tmp/cs4/ext1 \
  --bind-addr 127.0.0.1:8141 --disable-update-check

实测：

[2026-10-27T11:56:07.184Z] info  Using config file /tmp/cs4/config.yaml
[2026-10-27T11:56:07.184Z] info  HTTP server listening on http://127.0.0.1:8141/
[2026-10-27T11:56:07.184Z] info    - Authentication is enabled
[2026-10-27T11:56:07.184Z] info  Session server listening on /tmp/cs4/ud1/code-server-ipc.sock

结论：--bind-addr 压过 config.yaml 的 bind-addr。

5.3 实测二：PASSWORD 覆盖 config.yaml 的 password

PASSWORD=envpass code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud2 --extensions-dir /tmp/cs4/ext2 \
  --bind-addr 127.0.0.1:8142 --disable-update-check

[2026-10-27T11:56:10.220Z] info  HTTP server listening on http://127.0.0.1:8142/
[2026-10-27T11:56:10.220Z] info      - Using password from $PASSWORD

登录验证：

envpass login: 302 -> http://127.0.0.1:8142/
config password login: 200

fromconfig 返回 200（登录页），envpass 返回 302（认证通过）。配置文件里的密码被环境变量覆盖。

5.4 实测三：HASHED_PASSWORD 压过 PASSWORD

PASSWORD=wrongpass \
HASHED_PASSWORD='$argon2id$v=19$m=65536,t=3,p=4$iPb1ZIY2e64aSh7RejIj8w$7N+uXtqHzON/yuhxSYFJUVT4GLIsolYLmK17hvVHT/E' \
code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud3 --extensions-dir /tmp/cs4/ext3 \
  --bind-addr 127.0.0.1:8143 --disable-update-check

[2026-10-27T11:56:13.343Z] info  HTTP server listening on http://127.0.0.1:8143/
[2026-10-27T11:56:13.343Z] info      - Using password from $HASHED_PASSWORD
q1w2e3r4 login: 302 -> http://127.0.0.1:8143/
wrongpass login: Incorrect password

即使 PASSWORD=wrongpass 同时存在，实际生效的仍是 HASHED_PASSWORD 对应的 q1w2e3r4。

5.5 实测四：PORT 覆盖 bind-addr 的端口

PORT=8144 code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud4 --extensions-dir /tmp/cs4/ext4 \
  --bind-addr 127.0.0.1:8141 --disable-update-check

[2026-10-27T11:56:16.512Z] info  HTTP server listening on http://127.0.0.1:8144/

命令行写的是 8141，环境变量 PORT=8144 最终生效。这是最容易“明明改了 bind-addr 却监听在旧端口”的原因。

5.6 实测五：`--auth none` 覆盖配置文件的 password 认证

code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud5 --extensions-dir /tmp/cs4/ext5 \
  --bind-addr 127.0.0.1:8145 --auth none --disable-update-check

[2026-10-27T11:56:19.539Z] info  HTTP server listening on http://127.0.0.1:8145/
[2026-10-27T11:56:19.539Z] info    - Authentication is disabled
root page: 200

/ 直接 200，不再 302 到登录页。仅在完全可信的本机/内网调试时使用。

5.7 实测六：`CODE_SERVER_CONFIG` 指定配置文件

CODE_SERVER_CONFIG=/tmp/cs4/config.yaml code-server \
  --user-data-dir /tmp/cs4/ud6 --extensions-dir /tmp/cs4/ext6 \
  --bind-addr 127.0.0.1:8146 --disable-update-check

[2026-10-27T11:56:22.714Z] info  Using user-data-dir /tmp/cs4/ud6
[2026-10-27T11:56:22.721Z] info  Using config file /tmp/cs4/config.yaml
[2026-10-27T11:56:22.721Z] info  HTTP server listening on http://127.0.0.1:8146/

5.8 实测七：`--user-data-dir` 与 `--extensions-dir`

code-server --user-data-dir /tmp/cs4/ud6 --extensions-dir /tmp/cs4/ext6 \
  --bind-addr 127.0.0.1:8146 --disable-update-check

[2026-10-27T11:56:22.714Z] info  Using user-data-dir /tmp/cs4/ud6
[2026-10-27T11:56:22.721Z] info  Session server listening on /tmp/cs4/ud6/code-server-ipc.sock

要点：extensions-dir 不指定时会自动落在 <user-data-dir>/extensions；两者要一起迁移，否则换数据目录后扩展会“消失”（实际是去了旧目录）。

5.9 实测八：`--cert` 自签 HTTPS 与 `--cert-host`

code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud7 --extensions-dir /tmp/cs4/ext7 \
  --bind-addr 127.0.0.1:8147 --cert --cert-host demo.local --disable-update-check

[2026-10-27T11:56:25.859Z] info  HTTPS server listening on https://127.0.0.1:8147/
[2026-10-27T11:56:25.859Z] info    - Using certificate for HTTPS: /root/.local/share/code-server/demo_local.crt
https root: 302

证书实测信息：

subject=CN = demo.local
issuer=CN = demo.local
notBefore=Oct 27 11:56:25 2026 GMT
notAfter=Oct 27 11:56:25 2027 GMT

⚠️ 注意：本次传了 --user-data-dir /tmp/cs4/ud7，但自签证书仍落在默认目录 /root/.local/share/code-server/ 下。生产环境不要依赖自签证书的落盘位置，直接挂载自有证书并用 cert + cert-key 指定绝对路径。

5.10 实测九：`--idle-timeout-seconds` 必须大于 60

code-server --config /tmp/cs4/config.yaml --user-data-dir /tmp/cs4/ud8 \
  --bind-addr 127.0.0.1:8148 --idle-timeout-seconds 60 --disable-update-check

[2026-10-27T11:56:29.818Z] error --idle-timeout-seconds must be greater than 60 seconds.
exit=1

环境变量路径同样校验：

CODE_SERVER_IDLE_TIMEOUT_SECONDS=60 code-server ...
# CODE_SERVER_IDLE_TIMEOUT_SECONDS must be a number
# --idle-timeout-seconds must be greater than 60 seconds.

5.11 实测十：`--app-name` 改变登录页标题

code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud9 --extensions-dir /tmp/cs4/ext9 \
  --bind-addr 127.0.0.1:8149 --app-name "运维工作台" --disable-update-check

curl -s http://127.0.0.1:8149/login | grep -oE "<title>[^<]*</title>"

<title>运维工作台 login</title>

5.12 实测十一：布尔开关组合

CS_DISABLE_FILE_DOWNLOADS=true code-server --config /tmp/cs4/config.yaml \
  --user-data-dir /tmp/cs4/ud10 --extensions-dir /tmp/cs4/ext10 \
  --bind-addr 127.0.0.1:8150 \
  --disable-file-uploads --disable-workspace-trust \
  --disable-telemetry --disable-update-check

{"status":"expired","lastHeartbeat":0}

进程正常启动，HTTP 200。这些开关不会在启动日志里逐项回显，验证方式是进入工作台确认对应菜单/操作被禁用，或用 curl 检查下载接口返回 403。

5.13 实测十二：`bind-addr` 省略端口

bind-addr: 127.0.0.1
auth: none

[2026-10-27T12:02:40.813Z] info  HTTP server listening on http://127.0.0.1/

源码对无端口地址按 80 处理（parseBindAddr 的 http 默认端口），不是 8080。写 bind-addr 时务必带端口。

六、典型配置模板

6.1 最小可用

bind-addr: 0.0.0.0:8080
auth: password
password: q1w2e3r4
cert: false

6.2 生产（反代 + 强密码 + 关闭外联检查）

bind-addr: 127.0.0.1:8080
auth: password
hashed-password: "$argon2id$v=19$m=65536,t=3,p=4$iPb1ZIY2e64aSh7RejIj8w$7N+uXtqHzON/yuhxSYFJUVT4GLIsolYLmK17hvVHT/E"
cert: false
user-data-dir: /var/lib/code-server
extensions-dir: /var/lib/code-server/extensions
disable-telemetry: true
disable-update-check: true
disable-workspace-trust: true
locale: zh-cn
app-name: 研发工作台
reconnection-grace-time: 10800
trusted-origins:
  - https://ide.example.com

要点：

bind-addr 只监听回环，外网由反向代理终止 TLS；
hashed-password 不落明文；
trusted-origins 必须与实际访问域名一致，否则登录 POST 可能被 Origin 校验拒绝；
reconnection-grace-time 与反代超时配套，见第七节。

6.3 子路径反代

bind-addr: 127.0.0.1:8080
auth: password
hashed-password: "..."
abs-proxy-base-path: /codeserver
trusted-origins:
  - https://ide.example.com

反向代理层把 /codeserver/ 剥前缀转发到 127.0.0.1:8080/；abs-proxy-base-path 用于绝对路径代理请求。具体 Nginx 写法见 Compose 篇第七节。

6.4 只允许本机免密调试

bind-addr: 127.0.0.1:8080
auth: none
disable-telemetry: true
disable-update-check: true

仅限本机；不要把 auth: none 和 0.0.0.0 一起用。

七、排障：配置为什么不生效

7.1 先看启动日志的三行

Using config file ...
Using user-data-dir ...
HTTP server listening on ...

这三行直接告诉你：读的是哪个配置文件、数据目录在哪、最终监听地址是什么。90% 的“配置不生效”在这三行里就能定位。

7.2 配置改了但端口没变

按 3.2 的顺序排查：

# 是否有 PORT 环境变量
env | grep -E '^PORT=|^CODE_SERVER_HOST='

# 命令行是否还有 --bind-addr
ps -ef | grep '[c]ode-server'

实测中 PORT=8144 会压过 --bind-addr 127.0.0.1:8141，最终监听 8144。

7.3 密码怎么改都不对

检查是否同时设置了 PASSWORD 或 HASHED_PASSWORD；
HASHED_PASSWORD 优先级最高；
哈希里的 $ 在某些模板/编排工具中会被当变量插值，需按工具规则转义；
改完配置必须重启进程，code-server 不热加载配置。

7.4 配置文件写错直接启动失败

error reading /path/config.yaml: Unknown option --not-a-real-key

说明键名拼错。对照第四节表格逐字核对；YAML 缩进错误则会报解析错误，通常带行号。

7.5 自签证书找不到 / 路径不符合预期

--cert 不带路径时会在默认数据目录生成 <cert-host>.crt/.key。如果同时改了 --user-data-dir，本次实测证书仍落在 /root/.local/share/code-server/。生产环境用自有证书：

cert: /etc/ssl/certs/ide.example.com.crt
cert-key: /etc/ssl/private/ide.example.com.key

7.6 反代后登录 403 / Origin 校验失败

把实际访问域名加入：

trusted-origins:
  - https://ide.example.com
  - https://ide.example.com:8443

协议、域名、端口任一不同都要单独列出。

7.7 改了 `extensions-dir` 扩展全没了

扩展不会跟着 user-data-dir 自动搬。迁移时两个目录一起复制：

cp -a /old/user-data /new/user-data
cp -a /old/extensions /new/extensions

否则新目录下只有空扩展列表，旧扩展仍在旧路径。

八、参数速查表（按使用频率）

场景	推荐参数
对外监听	`bind-addr: 0.0.0.0:8080`（或反代时 `127.0.0.1:8080`）
强密码	`hashed-password` + `HASHED_PASSWORD`
关闭外联	`disable-telemetry: true`、`disable-update-check: true`
中文界面	`locale: zh-cn`
自定义标题	`app-name: 研发工作台`
子路径反代	`abs-proxy-base-path` + `trusted-origins`
防断线	`reconnection-grace-time: 10800` + 反代超时 86400s
空闲回收	`idle-timeout-seconds: 1800`（必须 > 60）
数据迁移	`user-data-dir` + `extensions-dir` 一起改
排障日志	`--log trace` 或 `verbose: true`

九、参考与站内互链

官方配置文档：https://coder.com/docs/code-server/latest/config
官方 FAQ（密码哈希、反代、证书）：https://coder.com/docs/code-server/FAQ
官方仓库：https://github.com/coder/code-server（v4.143.1，2026-10-27 实查）
站内上一篇：站内部署篇
站内首篇：《code-server 4.143.1 介绍与选型指南》
站内安装篇：《Ubuntu 22.04 安装 code-server 4.143.1 指南》

code-server 4.143.1 配置参数详解

code-server 4.143.1 配置参数详解

一、环境信息

二、配置文件在哪、怎么加载

2.1 默认路径

2.2 指定其他配置文件

2.3 配置键与命令行参数一一对应

三、优先级：命令行 > 环境变量 > config.yaml

3.1 总原则

3.2 监听地址的优先级细节

3.3 密码来源优先级

四、config.yaml 全项清单

4.1 监听、配置与认证

4.2 安全与访问控制

4.3 数据目录与扩展

4.4 网络、代理与子路径

4.5 运行、日志与界面

五、环境变量映射与 12 组实测

5.1 环境变量映射表

5.2 实测一：CLI 覆盖 config.yaml 的监听地址

5.3 实测二：PASSWORD 覆盖 config.yaml 的 password

5.4 实测三：HASHED_PASSWORD 压过 PASSWORD

5.5 实测四：PORT 覆盖 bind-addr 的端口

5.6 实测五：--auth none 覆盖配置文件的 password 认证

5.7 实测六：CODE_SERVER_CONFIG 指定配置文件

5.8 实测七：--user-data-dir 与 --extensions-dir

5.9 实测八：--cert 自签 HTTPS 与 --cert-host

5.10 实测九：--idle-timeout-seconds 必须大于 60

5.11 实测十：--app-name 改变登录页标题

5.12 实测十一：布尔开关组合

5.13 实测十二：bind-addr 省略端口

六、典型配置模板

6.1 最小可用

6.2 生产（反代 + 强密码 + 关闭外联检查）

6.3 子路径反代

6.4 只允许本机免密调试

七、排障：配置为什么不生效

7.1 先看启动日志的三行

7.2 配置改了但端口没变

7.3 密码怎么改都不对

7.4 配置文件写错直接启动失败

7.5 自签证书找不到 / 路径不符合预期

7.6 反代后登录 403 / Origin 校验失败

7.7 改了 extensions-dir 扩展全没了

八、参数速查表（按使用频率）

九、参考与站内互链

5.6 实测五：`--auth none` 覆盖配置文件的 password 认证

5.7 实测六：`CODE_SERVER_CONFIG` 指定配置文件

5.8 实测七：`--user-data-dir` 与 `--extensions-dir`

5.9 实测八：`--cert` 自签 HTTPS 与 `--cert-host`

5.10 实测九：`--idle-timeout-seconds` 必须大于 60

5.11 实测十：`--app-name` 改变登录页标题

5.13 实测十二：`bind-addr` 省略端口

7.7 改了 `extensions-dir` 扩展全没了