Sails CLI 版本查询命令 `sails --version` 完全指南：全局与本地版本辨析

• 后端

sails --version是 Sails 命令行工具（CLI）中最基础也最容易被忽略的一个命令，它用于查询当前机器上全局安装的 Sails 版本号，是排查"命令可用但行为异常""版本不一致导致 API 差异"等问题的第一道排查工具。读完本文，你将掌握sails --version的全部用法与等价变体、它的底层实现原理，以及如何正确区分并查询全局版本与项目本地版本。

命令用途与基本语法

--version参数用于获取你电脑上全局安装的 Sails 命令行工具版本号，即通过npm install -g sails安装的那个 Sails 的版本。

sails --version

执行后终端会直接输出一个语义化版本号（SemVer），例如：

$ sails --version 1.0.0

说明：上文示例输出1.0.0是 sailsversion.md 中的示意结果；本仓库（package.json）当前版本为1.5.18，因此实际运行sails --version在多数环境下会输出类似1.5.18的版本号，具体以你安装的版本为准。

等价的命令变体：-v/-V/version

虽然文档标题写的是sails --version，但从源码实现看，这个命令在 CLI 解析层有多个等价的触发形式。查看 bin/sails.js 可以发现，Sails 使用commander库注册版本参数：

// bin/sails.js var program = require('./private/patched-commander'); var sailsPackageJson = require('../package.json'); program .version(sailsPackageJson.version, '-v, --version');

并且源码中对版本参数做了大小写不敏感归一化处理：

// bin/sails.js // make `-v` option case-insensitive process.argv = _.map(process.argv, function(arg) { return (arg === '-V') ? '-v' : arg; });

因此以下四种写法在效果上是完全等价的，都会输出全局 Sails 版本：

$ sails --version $ sails -v $ sails -V // 大小写不敏感，会被归一化为 -v $ sails version // 显式注册的 version 子命令

其中sails version是通过注册一个名为version的子命令实现的，其动作指向program.versionInformation：

// bin/sails.js program .command('version') .description('') .action(program.versionInformation);

而versionInformation是在 bin/private/patched-commander.js 中对 commander 的猴子补丁（monkey-patch）：

// bin/private/patched-commander.js // Force commander to display version information. program.Command.prototype.versionInformation = program.versionInformation = function() { program.emit('version'); };

它通过触发 commander 的version事件，最终打印出注册的版本号字符串。值得注意的一个细节是，版本号并非硬编码，而是从package.json动态读取的（sailsPackageJson.version），这意味着 Sails 主模块每次发版时，CLI 的版本信息会自动同步更新，无需额外维护一份重复的版本常量。这正是 package.json 中"version": "1.5.18"与sails --version输出保持一致的底层原因。

全局版本与项目本地版本的区别

这是sails --version最容易引发困惑的一点：它报告的是全局安装的 Sails CLI 版本，而不是你当前项目内使用的 Sails 版本。

不同 Sails 应用可以拥有各自独立的、不同版本的本地 Sails 安装，因为每个项目都把自己的依赖封装在各自的node_modules/目录中。全局版本只影响sails命令本身的可执行性，而项目实际运行的框架代码来自项目内的node_modules/sails。

要查看某个特定项目内本地安装的 Sails 版本，需要在该项目目录下运行：

$ npm ls sails

该命令会列出当前项目依赖树中sails的实际解析版本。典型输出形如：

my-app@1.0.0 /path/to/my-app └── sails@1.5.18

版本选择的实际行为：本地优先

理解全局与本地版本的区别，关键还在于知道 CLI 在执行具体命令时优先使用本地版本。以 bin/sails-lift.js 中sails lift的注释与实现为例，其说明明确指出：如果当前目录下存在node_modules/sails，会使用它而非全局安装的 Sails。也就是说：

• sails --version→ 报告全局版本；
• sails lift/sails console/sails migrate等命令 → 在项目目录下优先加载本地版本的 Sails 来运行应用。

这意味着即使你全局安装了旧版本，只要项目node_modules/里锁定了新版本，应用依然会以新版本的框架代码运行。反之，如果项目目录下没有本地安装（例如裸目录中直接运行命令），CLI 才会回退到全局版本。

排查版本问题的实操流程

当遇到"文档说某 API 存在但项目里报错"之类的异常时，建议按以下顺序核对版本：

1. 查看全局版本：sails --version；
2. 进入项目目录查看本地版本：npm ls sails；
3. 若两者不一致，以本地版本对应的文档（版本升级指南）为准，判断是否为跨大版本迁移导致的破坏性变更；
4. 需要升级全局 CLI 时，使用npm install -g sails@^1.0.0指定目标版本范围，升级完成后可用sails --version验证。

与其他 CLI 命令的配套使用

sails --version属于 Sails CLI 命令家族的一员。完整的命令清单与总览见 Command-line interface (CLI)，该参考页指出 CLI 提供创建（sails new）、启动（sails lift）、调试（sails debug/sails inspect）以及版本信息获取等能力。与版本相关的常用场景包括：

• 配合 sails lift 排查"全局与本地版本混用"问题，例如生产服务器上forever start app.js启动应用前，先用sails --version确认服务器上全局 CLI 环境（参见 部署 FAQ 中npm install -g sails的服务器部署步骤）；
• 配合 sails upgrade 进行大版本迁移前，先确认当前全局版本，再决定是否安装新版 CLI 执行迁移工具。

小结

一句话总结：sails --version是确认"命令行工具本身"版本的快捷途径，而真正决定应用运行行为的，始终是每个项目node_modules/中的本地 Sails 版本——两者的差异正是排查版本相关问题的关键切入点。

• 后端