sublime text 没有传统ide式项目工程,仅通过 .sublime-project 文件定义轻量工作区:需先 open folder… 再 save project as…,文件须存于根目录且命名合法,配置通过 settings 覆盖全局,但必须显式加载项目文件才生效。

Sublime Text 有没有传统意义上的“项目工程”?
没有。Sublime Text 从不维护 IDE 那种带生命周期、依赖管理和构建上下文的“工程”,它只有「工作区(workspace)」和「项目定义(project definition)」两个轻量概念。真正的项目行为,全靠一个叫 .sublime-project 的 JSON 文件驱动——它不编译、不索引、不分析依赖,只负责告诉 Sublime:“这个窗口该打开哪些文件夹、用什么设置、怎么分组视图”。
-
.sublime-project必须保存在项目根目录下,且文件名不能含空格或中文(比如my-app.sublime-project合法,my app.sublime-project会失效) - 它必须和实际打开的文件夹绑定:没通过
File → Open Folder…打开过目录,Project → Save Project As…就是灰色不可点的 - 窗口标题栏显示项目名(如
my-app — Sublime Text),这是唯一可靠的“项目已激活”信号
如何正确创建并保存一个可复用的项目?
关键不是“新建”,而是“先开夹,再存档”。Sublime 不允许从空窗口直接建项目。
- 先点击
File → Open Folder…,选中你的项目根目录(比如/Users/me/my-python-project) - 此时侧边栏出现文件树,菜单
Project → Save Project As…才可用 - 保存路径必须选进刚才打开的那个文件夹里,文件名填
my-python-project.sublime-project - 保存后,Sublime 自动在同目录生成配套的
my-python-project.sublime-workspace(记录当前打开了哪些文件、分组状态等,不建议提交到 Git)
常见错误现象:
- 保存后双击
.sublime-project文件,结果只打开一个空窗口 → 没提前用Open Folder…加载过上下文,或路径写死了绝对路径(应优先用"path": ".") - 用命令行
subl --project xxx.sublime-project启动失败 → 文件里folders数组为空或含非法字段(最小合法结构是{"folders": [{"path": "."}]})
怎么让某个项目用独立缩进、编码、构建系统?
全靠 settings 字段覆盖全局配置,作用域严格限定在该项目内打开的所有文件。
- 在
Project → Edit Project中,往 JSON 里加"settings"对象即可,例如:
{
"folders": [{"path": "."}],
"settings": {
"tab_size": 4,
"translate_tabs_to_spaces": true,
"default_encoding": "UTF-8",
"rulers": [88],
"build_systems": [{
"name": "Python - v3.11",
"cmd": ["python3.11", "$file"],
"selector": "source.python"
}]
}
}
注意:
- 修改后不会热更新:必须关闭整个窗口,再用
Project → Open Project…重新加载,或双击该.sublime-project文件 - 插件是否响应这些设置,取决于它读取的是
view.settings().get("xxx")还是硬编码的全局Preferences.sublime-settings;验证方法是在 Python 控制台运行sublime.active_window().active_view().settings().get("my_test_flag") -
folder_exclude_patterns和file_exclude_patterns是写在folders数组里的,不是settings下,放错位置就无效
为什么改了配置却没生效?最常被忽略的三个点
-
.sublime-project 文件被保存到了错误位置(比如桌面或 Sublime 默认 Packages 目录),导致 Sublime 根本没加载它;正确做法是:保存时路径必须指向你用 Open Folder… 打开的那个文件夹
- 用了绝对路径写
"path": "/Users/me/project",换电脑或换用户就崩;一律用 "path": "." 或 "path": "${folder:src}"(需插件支持变量扩展)
- 认为“只要打开这个文件夹,项目配置就自动生效”——错。必须通过
Project → Open Project… 显式加载那个 .sublime-project 文件,或者用 subl --project /path/to/project.sublime-project 启动;单纯 Open Folder… 只是加载文件树,不触发项目上下文
.sublime-project 文件被保存到了错误位置(比如桌面或 Sublime 默认 Packages 目录),导致 Sublime 根本没加载它;正确做法是:保存时路径必须指向你用 Open Folder… 打开的那个文件夹"path": "/Users/me/project",换电脑或换用户就崩;一律用 "path": "." 或 "path": "${folder:src}"(需插件支持变量扩展)Project → Open Project… 显式加载那个 .sublime-project 文件,或者用 subl --project /path/to/project.sublime-project 启动;单纯 Open Folder… 只是加载文件树,不触发项目上下文项目配置真正起效的前提,从来不是“文件存在”,而是“窗口由该项目文件驱动”。这点不厘清,后面所有设置都是空中楼阁。











