用 Windsurf 同时维护多个项目时,最先要解决的是模型参数隔离问题。全局配置适合日常默认项目,但一旦某个仓库需要不同的模型版本、不同的 temperature 范围,甚至要指向不同的网关,全局配置就会变成绊脚石。这类问题不适合用“每次开会前手动切一下”的方式解决,项目级配置才是该用的机制。
先把配置放进 .windsurf 目录
在项目根目录建立一个 .windsurf 文件夹,并在其中放置项目的模型配置文件。Windsurf 会优先读取这个目录下的设置,覆盖全局配置。具体来说,在编辑器内打开命令面板,执行 “Open Project Settings” 会直接创建或打开该文件,避免手工找路径。改动保存后,当前项目的模型参数就与其它项目隔离,切换项目时不会互相污染。
这里的“项目根目录”指的是打开 Windsurf 时作为工作区根目录的那个文件夹。如果你经常直接打开子目录,或者在多根目录工作区中把几个仓库拖到一起,根目录并不是某个仓库的根,而是 .code-workspace 文件所在的位置。这时需要给每个仓库单独建立配置文件,或者用工作区级配置统一指定。
项目配置只写要覆盖的字段
项目级配置并非所有字段都必须全量书写,它会与全局配置合并。只有你明确写出的模型参数才会覆盖全局值,其余沿用全局。因此当你要让项目 A 使用与全局不同的温度或模型版本时,只需在项目配置中列出等待覆盖的字段。这样能减少维护成本,也避免因为遗漏默认值导致项目行为异常。常见的一个坑是误以为项目级配置需要完整复制全局配置,结果全局更新后项目还锁死在旧值。
举个例子,你的全局配置用了 model: "default-model",但项目 A 是文档站,希望用更克制的 temperature 值 0.2,项目 B 是代码生成,想用 0.8。你不需要把整个模型参数复制到两个项目,只需在每个项目的配置中写一个 temperature 字段。下面是一个示意结构,具体字段名以编辑器 schema 为准:
{
"model": "project-specific-model",
"temperature": 0.2
}
注意,当全局更新默认模型后,未覆盖该字段的项目会跟随全局变化;如果曾经在某个项目里全量复制过全局配置,那该项目的模型就被锁死,除非手动更新。这是覆盖规则带来的一个风险边界,需要在改动模型时留意。
连接信息与敏感项单独处理
模型参数不只是模型名一个字段,base URL、API Key 这类连接信息同样需要隔离。不同项目可能走不同的网关,比如 A 项目走公司内网代理,B 项目直连官方接口。把这些信息写进项目配置没问题,但不要把明文密钥写进去。
建议在配置里引用环境变量,例如用 "${PROJECT_BASE_URL}" 占位,并在启动脚本或 shell 中导出实际值。这样项目之间真正隔离,同时密钥不会进版本库。在团队共享时,更要把文件拆分——提交一个 settings.default.json 作为模板,让开发者自行复制为 settings.json,并在 .gitignore 中忽略后者。项目通用的模型名称、参数范围留在这个模板里,个人密钥和测试值放在本地的私有文件里。否则,共享配置中直接改模型参数,团队成员拉取代码后就被切换模型,往往会打乱调试预期。
改完怎么确认真的生效
配置完成后,别急着写代码。在 Windsurf 的聊天或编辑侧栏会显示当前生效的模型名。如果显示的模型名称和你项目里指定的一致,说明配置加载成功;如果不一致,先检查工作区根目录是否正确——你打开项目时选错了文件夹,配置文件就不在搜索范围内。还有一种情况是多个文件夹一起打开时,配置文件放错层级。按前文所说,.windsurf 目录必须和 .code-workspace 同层。
不生效时按顺序排查
当项目配置看起来没生效,先按优先级排查:全局配置是否锁定;配置文件是否在正确目录;JSON 格式是否合法;参数名是否与当前 Windsurf 版本匹配。最容易犯的是参数名写错,比如把 `temperature` 写成 `temprature`,配置文件解析时不会报错,但会被忽略。这时不会看到任何错误提示,只有模型行为与预期不符。建议打开配置文件时检查编辑器提示的 schema 校验,有红色波浪线就说明字段名或格式有问题,及时修正。
按优先级排查的思路不仅适用于模型参数,也适合大多数项目配置场景。全局配置锁定不是指软件层面的禁止修改,而是说你可能有多个全局配置源,或者某个插件强制覆盖了项目级配置。另外,schema 校验是关键,Windsurf 的编辑器通常会给出 JSON schema 提示,看到红色波浪线就说明字段名或类型有问题。修正后如果还未生效,可以考虑关闭并重新打开项目,因为某些参数在会话启动时读取,修改后热加载不一定及时。
项目级模型参数隔离并不复杂,核心是记住三条:配置文件放在正确的工作区根目录;只覆盖需要改变的字段;连接信息用环境变量传递。这样你切换项目时,Windsurf 会把模型、温度、端点都切到对应项目,不用再依赖记忆去手动改回。