Templ插件需手动关联语言模式并启用，确保VSCode以templ模式打开文件；Go模块根目录必须正确，gopls需索引生成代码；推荐用task+save hook替代watch实现稳定自动编译。

Templ 插件装了但没高亮？检查是否启用语言服务

Templ 文件（.templ）默认不被 VSCode 识别为 Go 相关语言，光装插件不够，必须手动关联语言模式。否则 templ 文件会以纯文本打开，语法高亮、补全、错误提示全失效。

• 打开任意 .templ 文件 → 右下角点击当前语言标识（比如“Plain Text”）→ 选择 Configure File Association for '.templ'... → 输入 templ 并选中 templ 语言模式
• 确认插件已启用：在扩展面板搜索 templ，确保 Templ Language Support（官方插件，作者是 ajkerrigan）状态为“已启用”
• 重启 VSCode 或用快捷键 Ctrl+Shift+P（Win/Linux）或 Cmd+Shift+P（macOS）执行 Developer: Reload Window

Go + Templ 混合项目里，templ generate 不生效？路径和工作区是关键

Templ 编译器需要明确知道 Go 模块根目录在哪，否则找不到 go.mod，生成的 Go 代码无法正确 import，甚至报 cannot find package 错误。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 确保 VSCode 打开的是 Go 模块根目录（即含 go.mod 的文件夹），不是其子目录
• 在终端中运行 templ generate 前，先 cd 到模块根目录；若用 VSCode 集成终端，注意终端启动路径是否匹配
• 如果使用 templ watch，它默认监听当前目录下所有 .templ，但生成路径仍以模块根为基准，建议在 go.mod 同级写 templ.json 显式配置：

  { "outDir": "./gen" }

补全失效或跳转不到定义？检查 Go 工具链和 gopls 状态

Templ 插件本身不提供语义跳转，它依赖 gopls 对生成后的 Go 代码进行索引。如果 gopls 没加载好模板生成的文件，就会出现“找不到定义”“补全只有基础关键字”等问题。

• 确认 gopls 已安装且版本 ≥ v0.14.0（Templ v0.2+ 要求）：运行 go install golang.org/x/tools/gopls@latest
• VSCode 设置中检查 "go.useLanguageServer": true 是否开启（默认已开）
• 生成后，等待右下角状态栏显示 gopls: indexing... 完成；可手动触发 Go: Restart Language Server
• 生成目录（如 gen/）不能被 go.work 或 go.mod 排除，否则 gopls 不扫描

保存自动编译失败？别依赖文件监视，用 task + save hook 更稳

VSCode 的文件保存事件（files.autoSave）和 Templ 的 watch 进程容易冲突，尤其在快速连保存时，常出现“文件被占用”或“生成代码滞后”。官方也不推荐在编辑器内长期跑 templ watch。

• 改用 VSCode Task：在 .vscode/tasks.json 中定义一个 templ generate 任务，并设 "isBackground": false
• 绑定保存动作：在 settings.json 加

  "emeraldwalk.runonsave": { "commands": [{ "match": "\.templ$", "cmd": "npx templ generate" }] }

  （需装 run-on-save 插件）
• 注意：npx templ generate 要求项目根有 package.json 或全局装了 templ CLI；更可靠的是用 go run github.com/a-h/templ/cmd/templ@latest generate

Templ 的核心逻辑是“写模板 → 生成 Go 代码 → 编译进主程序”，VSCode 所有功能都围绕这个链条展开。最容易被忽略的是：它不是传统意义上的“语法高亮插件”，而是一个轻量语言服务器 + 生成流程协调器——一旦生成环节断掉，编辑体验就立刻退化回普通文本。