OpenResty Nginx Helper

为 Nginx / OpenResty 配置文件提供完整开发体验：语法高亮、上下文补全、格式化、跳转、诊断与悬浮文档。 Complete development experience for Nginx / OpenResty config files: syntax highlighting, context-aware completion, formatting, go-to-definition, diagnostics and hover docs.

功能特性

Features

语法高亮

Syntax Highlighting

• Nginx 指令、块关键字、变量、字符串、注释与数字单位的完整高亮，内置 200+ 指令。
• Full highlighting for Nginx directives, block keywords, variables, strings, comments and numeric units, with 200+ built-in directives.
• 覆盖 OpenResty 指令与全部 14 个 *_by_lua_block 阶段指令。
• Covers OpenResty directives and all 14 *_by_lua_block phase directives.
• *_by_lua_block {} 内部自动嵌入 Lua 语法高亮：关键字、字符串、注释、table 与运算符。
• Auto-embedded Lua highlighting inside *_by_lua_block {}: keywords, strings, comments, tables and operators.
• Lua 代码块使用浅色背景，与 Nginx 配置在视觉上清晰区分。
• Lua blocks use a light background to visually separate them from Nginx config.

上下文感知补全

Context-Aware Completion

• 按块层级智能推荐，当前块专属指令排序靠前。
• Smart suggestions based on block hierarchy, with the current block's directives ranked first.
• Lua 块内提供 Lua 关键字、标准库、OpenResty ngx.* API 以及当前文件自定义符号。
• Inside lua blocks: Lua keywords, standard library, OpenResty ngx.* API and symbols defined in the current file.
• 支持级联补全：ngx.header.、ngx.var.、共享字典方法、require 模块方法逐级展开。
• Cascading completion: ngx.header., ngx.var., shared-dict methods and require-module methods expand level by level.
• 为响应头字段提供固定预制值，如 content_type 补全常见 MIME 类型。
• Provides fixed preset values for response header fields, e.g. common MIME types for content_type.

格式化

Formatting

• Nginx 配置按块深度自动缩进。
• Auto-indents Nginx config by block depth.
• Lua 块内代码使用 StyLua 格式化，并自动对齐基准缩进。
• Lua code inside blocks is formatted with StyLua and aligned to the base indentation.
• Lua 存在语法错误时回退到简单缩进，并自动去除块前后多余空行。
• Falls back to simple indentation on Lua syntax errors, and removes extra blank lines around blocks.
• 支持格式化整个文档或选中区域。
• Supports formatting the whole document or a selected range.

跳转

Go-to-Definition

• require("module") 基于 lua_package_path 跳转到对应 Lua 文件，找不到时回退工作区搜索。
• require("module") jumps to the Lua file via lua_package_path, falling back to workspace search.
• *_by_lua_file 路径、ngx.* API、Lua 标准库函数均可跳转。
• *_by_lua_file paths, ngx.* APIs and Lua standard library functions are all navigable.
• 支持父级回退，如 ngx.var.remote_addr 跳转到 ngx.var 声明。
• Supports parent fallback, e.g. ngx.var.remote_addr jumps to the ngx.var declaration.

诊断

Diagnostics

• 无法解析的 require("module") 导入显示错误提示。
• Unresolved require("module") imports are flagged with an error.
• 自动识别 LuaJIT 标准库与 OpenResty 内置模块，避免误报。
• Recognizes LuaJIT standard library and OpenResty built-in modules to avoid false positives.
• 检查 Lua 代码的块配对、括号配对与未闭合字符串。
• Checks Lua block pairing, bracket pairing and unclosed strings.

悬浮文档与参数提示

Hover Documentation & Signature Help

• 悬浮在指令或 API 上显示说明，*_by_lua_block 展示执行阶段详情与官方链接。
• Hovering over a directive or API shows its description; *_by_lua_block shows phase details with official links.
• 输入函数时提示参数签名，输入括号或逗号自动触发。
• Shows parameter signatures while typing a function, triggered by parentheses or commas.

其他

Other

• 启动时检测可能冲突的 Nginx 相关插件并给出提示。
• Detects potentially conflicting Nginx-related extensions on startup.
• 支持 Ctrl+/ 行注释、括号自动闭合与 #region 折叠。
• Supports Ctrl+/ line comments, auto-closing brackets and #region folding.

文件匹配

File Association

以下文件会自动识别为 Nginx 语言，也可在右下角状态栏手动切换。 The following files are auto-detected as the Nginx language; you can also switch manually via the bottom-right status bar.

配置

Configuration

指定为默认格式化器

Set as Default Formatter

在 .vscode/settings.json 中添加以下内容： Add the following to .vscode/settings.json:

{
  "[nginx]": {
    "editor.defaultFormatter": "tianzehao.openresty-nginx-helper",
    "editor.formatOnSave": true
  }
}

也可以右键选择“使用...格式化文档”，再选择 OpenResty Nginx Helper。 You can also right-click, choose “Format Document With...”, then select OpenResty Nginx Helper.

已知限制

Known Limitations

• 遇到 Lua 代码中复杂嵌套花括号时，语法高亮范围可能提前结束，补全与格式化逻辑不受影响。
• With complex nested braces in Lua, the highlight range may end early; completion and formatting are unaffected.
• 采用静态补全与轻量符号提取，不连接 Lua 语言服务器，不做完整类型推断。
• Uses static completion and lightweight symbol extraction without a Lua language server or full type inference.

许可证

License

MIT 许可证。 Licensed under the MIT License.