NetSuite SuiteScript Navigator
一款面向 NetSuite SDF / SuiteScript 2.x 的 VS Code 扩展。目标是把 SuiteCloud IDE(WebStorm/IntelliJ 插件)里最常用的“跨文件跳转”体验带到 VS Code:
F12 / Ctrl+Click 从自定义模块调用跳到另一个文件里的函数、类、对象成员
Shift+F12 查找某个模块导出函数在哪些脚本中被调用
- 从
N/record、N/search、N/log 等内置模块跳到随扩展打包的 NetSuite API 声明
- 支持 JSDoc
@typedef、@param、@returns 和 AMD / CommonJS / ES Module 依赖
- 支持未保存缓冲区、懒加载没有
@NApiVersion 的私有模块、类实例方法、返回值类型推断
扩展完全在本地工作,不读取 NetSuite 账号,不发起网络请求。
功能
| 功能 |
说明 |
| 转到定义 |
自定义 AMD 模块、嵌套对象导出、类/实例方法、N/* 模块、JSDoc 类型、模块路径字符串 |
| 查找引用 |
模块导出函数/常量在所有文件中的 alias.fn、alias.nested.fn 引用 |
| 悬停文档 |
函数签名、JSDoc 描述、参数、返回值、@since、@governance |
| 文档大纲 |
模块导出和顶层声明,类/接口成员可展开 |
| 工作区符号 |
Ctrl+T 搜索所有 SuiteScript 模块中的导出符号 |
| 补全 |
taxCalculator. 补全模块导出;record. 补全 NetSuite API;N/ 补全内置模块名 |
| 模块图 |
命令面板运行 SuiteScript: Show Module Graph 查看模块依赖 |
| 状态栏 |
显示已索引模块数,点击查看索引详情/重建索引 |
跳转示例
/**
* @NApiVersion 2.1
* @NScriptType UserEventScript
*/
define(['N/record', './lib/taxCalculator'], (record, taxCalculator) => {
function beforeSubmit(context) {
const rec = record.create({ type: record.Type.INVOICE }); // record.create -> N/record.d.ts
const result = taxCalculator.calculateTax(100); // F12 -> lib/taxCalculator.js
rec.setValue({ fieldId: 'memo', value: result.amount }); // Record.setValue -> N/record.d.ts
}
return { beforeSubmit };
});
// lib/taxCalculator.js
define(['./constants'], (constants) => {
/**
* @typedef {Object} TaxResult
* @property {number} amount
* @property {number} rate
*/
/**
* @param {number} amount
* @returns {TaxResult}
*/
function calculateTax(amount) {
return { amount: amount * constants.DEFAULT_RATE, rate: constants.DEFAULT_RATE };
}
return { calculateTax };
});
- 在
taxCalculator.calculateTax 上按 F12:跳到 calculateTax 声明
- 在
calculateTax 声明上按 Shift+F12:列出所有调用它的脚本
- 在
result.amount 上按 F12:跳到 @typedef TaxResult 的 amount 属性
- 在
'./lib/taxCalculator' 字符串上按 F12:打开模块文件
- 在
record.Type 上按 F12:打开 N/record.d.ts 中的 Type 枚举
支持的代码形态
- SuiteScript 2.x AMD:
define(['N/record', './lib/foo'], function(record, foo) { ... })
- 简化 CommonJS 包装:
define(function(require, exports, module) { ... })
require:const foo = require('./lib/foo')、const { fn } = require('./lib/foo')
- ES Module(TypeScript 源码 /
.d.ts):import { fn } from './lib/foo'、export function
- 对象命名空间导出:
return { format: { money } }
- 别名导出:
return { calculate: calculateTax }
- 类:
class TaxCalculator { calculate() {} }、new classHelper.TaxCalculator().calculate()
- JSDoc:
@typedef、@property、@param、@returns、@type、import('./x').Type
- N/ 内置模块*:随扩展打包 60 个 NetSuite 声明文件,涵盖
N/record、N/search、N/query、N/ui/serverWidget、N/https、N/llm 等
- SuiteScript 1.0 文件:可以索引和浏览顶层函数;但 1.0 的全局
nlapi* API 没有内置声明(见下方限制)
安装
从 VSIX 安装
code --install-extension netsuite-suitescript-navigator-0.1.0.vsix
安装后打开任意包含 manifest.xml、src/FileCabinet/SuiteScripts/ 或带 @NApiVersion 的 JS/TS 工作区,扩展会自动建立索引。状态栏出现 SuiteScript: N modules 即表示就绪。
开发模式
npm install
npm run build
在 VS Code 中按 F5,会启动一个加载了本扩展的“扩展开发宿主”,并打开 test/fixtures/project 示例项目。
npm run watch # 监听并重新打包
npm run check # TypeScript 类型检查
npm test # 核心索引/跳转测试
npm run package # 生成 .vsix
本仓库在受限 Windows 沙箱里开发时使用 npm install --ignore-scripts 和原生 esbuild CLI 构建;普通开发环境直接 npm install 即可。
配置
所有设置位于 settings.json 的 suitescriptNavigator.*:
| 设置 |
默认值 |
说明 |
suitescriptNavigator.enabled |
true |
是否启用跳转能力 |
suitescriptNavigator.include |
**/*.js 等 |
索引文件 glob |
suitescriptNavigator.exclude |
node_modules 等 |
排除 glob |
suitescriptNavigator.maxFiles |
5000 |
单次索引最多检查的文件数 |
suitescriptNavigator.indexAllJavaScript |
false |
为 true 时索引所有 JS/TS,即使没有 SuiteScript 标记 |
suitescriptNavigator.builtinModules |
true |
是否加载随扩展打包的 N/* 声明 |
suitescriptNavigator.trace |
false |
输出详细索引/解析日志 |
大型项目
默认只索引包含以下任一特征的文件:
- 含
@NApiVersion 或 @NScriptType
- 位于
SuiteScripts、SuiteApps 或 FileCabinet 目录
- AMD 依赖中包含
N/*
被其他模块 import 的私有文件即使没有标记,也会在解析依赖时按需加载。如果自定义模块目录很特殊,可设置 indexAllJavaScript: true,或调整 include。
限制
- 不是完整的 TypeScript 类型检查器。扩展使用轻量 AST + JSDoc + 返回值推断,重点解决 SuiteScript 模块间的导航;复杂泛型、条件类型、交叉类型不会做完整语义分析。
- 查找引用主要针对模块导出。同文件局部变量的引用由 VS Code 内置 JavaScript/TypeScript 语言服务提供;本扩展补充跨文件引用。实例方法(例如
rec.setValue)的“查找引用”目前不如“转到定义”完整。
- SuiteScript 1.0 全局 API 没有内置声明。1.0 文件可以索引,但
nlapi* 全局函数不会跳到定义。
- N/ 类型声明来自第三方*:
@hitc/netsuite-types 2026.2.8(MIT)。若 Oracle 发布新的 API,可更新 resources/netsuite-types/。
- 补全是按模块导出列表提供的轻量补全,不是完整签名感知补全。
- Webview 模块图最多展示前 400 个模块,避免超大工作区卡顿。
架构
src/
core/
parser.ts TypeScript AST -> SuiteScript 模块模型(依赖/导出/类/JSDoc/作用域)
jsdoc.ts JSDoc 解析,含 @typedef/@property 和类型位置
index.ts 工作区索引、N/* 声明、路径解析、按需加载
resolver.ts 定义/引用/悬停/补全/大纲的解析引擎
types.ts 核心数据模型(与 VS Code API 无关)
providers/ VS Code Language Features 适配层
service.ts 索引生命周期、打开缓冲区、配置热重建
extension.ts activation、命令、状态栏、文件监听
resources/
netsuite-types/ 打包的 NetSuite N/* 声明(MIT,见 LICENSE)
解析与索引层不依赖 vscode,因此可以在纯 Node 环境做单元测试。VS Code 层只负责位置/URI 转换和注册 Provider。
测试
npm test 会编译并运行 17 个核心场景,包括:
- AMD 相对路径解析(含省略
.js)
- 自定义模块函数跳转
- 嵌套对象成员跳转
N/record.create() 返回值 -> Record.setValue 跳转
- 类实例方法跳转
- JSDoc typedef / 属性 / 类型标注跳转
- 跨文件查找引用(自定义模块和
N/log)
- 解构参数、CommonJS
require
- 无
@NApiVersion 私有模块懒加载
- TypeScript ES import/export
- 未保存缓冲区更新
集成测试位于 test/vscode/,通过真实 VS Code 扩展宿主验证 Provider 注册与跳转。它需要桌面环境:
npm run test:vscode
发布
当前扩展的 publisher 已设置为 nubanjiang,扩展 ID 为:
nubanjiang.netsuite-suitescript-navigator
生成可分发 VSIX:
npm run package
发布到 Marketplace 前需要先在 Visual Studio Marketplace 管理页面 创建 nubanjiang publisher,并准备 Azure DevOps Personal Access Token(Marketplace > Manage 权限)。然后可以执行:
npx vsce login nubanjiang
npx vsce publish --packagePath netsuite-suitescript-navigator-0.1.0.vsix
或直接使用 Token:
npx vsce publish -p <YOUR_PAT> --packagePath netsuite-suitescript-navigator-0.1.0.vsix
如果 0.1.0 已经发布过,请先更新 package.json 中的 version 再重新打包。建议发布前补充 repository、homepage 和 bugs 字段,便于用户在 Marketplace 查看源码和反馈问题。
第三方声明
- NetSuite
N/* 类型声明:@hitc/netsuite-types,MIT License,版权归 Head in the Cloud Development。
- 声明文件的完整许可证保存在
resources/netsuite-types/LICENSE。
本扩展与 Oracle / NetSuite 无隶属关系。NetSuite、SuiteScript 是 Oracle 的商标。