企业官网建设流程全解析

code-server 代理的预检请求被认证拦截怎么解决（--skip-auth-preflight）？

【免费下载链接】code-serverVS Code in the browser项目地址: https://gitcode.com/GitHub_Trending/co/code-server

当 code-server 开启了密码认证（默认配置即如此），通过内置代理访问本地 Web 服务时，浏览器发出的预检请求（OPTIONS）会被认证机制拦截：预检请求本身不携带凭据，而 code-server 默认对所有代理请求（包括预检请求）做认证，于是这类请求拿不到目标服务的正常响应。解决方式是加上--skip-auth-preflight参数，让所有预检请求绕过认证直接通过代理。本文说明如何确认该问题、在哪里加参数，以及如何验证修复生效。

问题出现的场景与现象

该问题只发生在同时满足两个条件时：

1. code-server 开启了认证。默认配置~/.config/code-server/config.yaml中就是auth: password，即默认就开着（见 docs/FAQ.md）；
2. 你在通过 code-server 的内置代理访问本地 Web 服务，即使用子路径/proxy/<port>/或子域名方式（--proxy-domain <domain>，见 docs/guide.md 的 “Accessing web services” 一节）。

未加参数时，未认证的 OPTIONS 请求会被拒绝（HTTP 401），项目的代理测试也固化了这一默认行为：带--auth=password启动时对代理路径发 OPTIONS 请求，返回 401（见 test/unit/node/proxy.test.ts 的 “should not allow OPTIONS without authentication by default” 用例）。

解决方案：启用 --skip-auth-preflight

--skip-auth-preflight是一个布尔开关，定义见 src/node/cli.ts，其官方描述为 “Allows preflight requests through proxy without authentication.”。启用后，代理路由对 OPTIONS 请求直接放行，不再执行认证检查（实现见 src/node/routes/pathProxy.ts 与 src/node/routes/domainProxy.ts）。

方式一：启动参数

在启动命令上追加该参数，例如：

code-server --skip-auth-preflight

如果你是用 systemd 管理的 code-server 服务，把参数加入服务的启动配置后重启：

sudo systemctl restart code-server@$USER

方式二：写入配置文件

根据 docs/FAQ.md 的说明，config 文件中的每个键直接对应一个code-server标志，且命令行标志优先于配置文件。因此也可以在~/.config/code-server/config.yaml中写入：

skip-auth-preflight: true

两种方式二选一即可，效果相同。

验证修复是否生效

两处可以核对：

1. 启动日志。启用该参数后，code-server 启动时会打印一行提示（源码见 src/node/main.ts）：

   - Skipping authentication for preflight requests

   看到这一行说明参数已被识别并生效。

2. 预检请求状态码。修复前后对代理路径的 OPTIONS 请求表现不同：默认认证开启时返回 401；加上--skip-auth-preflight后返回 200。项目测试 test/unit/node/proxy.test.ts 的 “should allow OPTIONS withskip-auth-preflightflag” 用例正是断言了这一点（--auth=password加--skip-auth-preflight时 OPTIONS 请求返回 200）。你也可以在浏览器中打开被代理的应用，观察控制台里预检请求是否不再因 401 而失败、应用能否正常加载。

作用范围与限制

• 该参数只放行OPTIONS 预检请求的认证检查；普通请求（GET/POST 等）仍然走正常认证，不影响 code-server 本身的登录保护。
• 文档原文的表述是 “允许所有预检请求不经过认证通过代理”（见 docs/guide.md 的 “Preflight requests” 一节），即这是针对全部代理预检请求的放行，无法按端口或路径部分放行。
• 该参数自 4.99.3（2025-04-17，对应 Code v1.99.3）版本引入，见 CHANGELOG.md；更早版本上没有此开关，遇到同类问题需要先升级或改用子域名代理等文档中的其他方式。

【免费下载链接】code-serverVS Code in the browser项目地址: https://gitcode.com/GitHub_Trending/co/code-server