npm-ls

概要

¥Synopsis

npm ls <package-spec>

alias: list

描述

¥Description

此命令将以树形结构打印到标准输出中已安装的包的所有版本，以及指定 --all 时它们的依赖。

¥This command will print to stdout all the versions of packages that are installed, as well as their dependencies when --all is specified, in a tree structure.

注意：要获得一个给定包为何包含在树中的 "一饮而尽" 视图，请使用 npm explain。

¥Note: to get a "bottoms up" view of why a given package is included in the tree at all, use npm explain.

位置参数是 name@version-range 标识符，它将结果限制为仅指定包的路径。请注意，嵌套包还将显示指定包的路径。例如，在 npm 的源代码树中运行 npm ls promzard 将显示：

¥Positional arguments are name@version-range identifiers, which will limit the results to only the paths to the packages named. Note that nested packages will also show the paths to the specified packages. For example, running npm ls promzard in npm's source tree will show:

npm@10.5.0 /path/to/npm
└─┬ init-package-json@0.0.4
  └── promzard@0.1.5

它将打印出无关的、丢失的和无效的包。

¥It will print out extraneous, missing, and invalid packages.

如果一个项目为依赖指定了 git url，这些会显示在 name@version 之后的括号中，以便用户更容易识别项目的潜在分支。

¥If a project specifies git urls for dependencies these are shown in parentheses after the name@version to make it easier for users to recognize potential forks of a project.

显示的树是基于包依赖的逻辑依赖树，而不是 node_modules 文件夹的物理布局。

¥The tree shown is the logical dependency tree, based on package dependencies, not the physical layout of your node_modules folder.

以 ll 或 la 运行时，默认显示扩展信息。

¥When run as ll or la, it shows extended information by default.

注意：设计变更待定

¥Note: Design Changes Pending

当 npm 创建一个天真地嵌套每个依赖的 node_modules 文件夹时，npm ls 命令的输出和行为非常有意义。在这种情况下，磁盘上包的逻辑依赖图和物理树将大致相同。

¥The npm ls command's output and behavior made a ton of sense when npm created a node_modules folder that naively nested every dependency. In such a case, the logical dependency graph and physical tree of packages on disk would be roughly identical.

随着 npm v3 中依赖的自动安装时数据去重的出现，ls 输出被修改为将逻辑依赖图显示为树结构，因为这对大多数用户更有用。但是，如果不使用 npm ls -l，大部分时间都无法显示包的实际安装位​​置！

¥With the advent of automatic install-time deduplication of dependencies in npm v3, the ls output was modified to display the logical dependency graph as a tree structure, since this was more useful to most users. However, without using npm ls -l, it became impossible to show where a package was actually installed much of the time!

随着在 npm v7 中自动安装 peerDependencies 的出现，这变得更加奇怪，因为 peerDependencies 在逻辑上是它们在依赖图中的依赖 "underneath"，但物理上总是位于或高于它们在磁盘上的位置。

¥With the advent of automatic installation of peerDependencies in npm v7, this gets even more curious, as peerDependencies are logically "underneath" their dependents in the dependency graph, but are always physically at or above their location on disk.

此外，自从 npm 获得 ls 命令（在 0.0.2 版中！）以来，依赖图通常会变得更大。因此，为了避免向终端转储过多的内容，npm ls 现在只显示顶层依赖，除非提供了 --all。

¥Also, in the years since npm got an ls command (in version 0.0.2!), dependency graphs have gotten much larger as a general rule. Therefore, in order to avoid dumping an excessive amount of content to the terminal, npm ls now only shows the top level dependencies, unless --all is provided.

目前正在对该命令的用例、意图、行为和输出进行彻底的重新检查。预计至少在 npm v8 中默认的人类可读的 npm ls 输出会有重大变化。

¥A thorough re-examination of the use cases, intention, behavior, and output of this command, is currently underway. Expect significant changes to at least the default human-readable npm ls output in npm v8.

配置

¥Configuration

all

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

运行 npm outdated 和 npm ls 时，设置 --all 将显示所有过时或已安装的包，而不仅仅是当前项目直接依赖的包。

¥When running npm outdated and npm ls, setting --all will show all outdated or installed packages, rather than only those directly depended upon by the current project.

json

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

是否输出 JSON 数据，而不是正常输出。

¥Whether or not to output JSON data, rather than the normal output.

• 在 npm pkg set 中，它可以使用 JSON.parse() 解析集合值，然后再将它们保存到你的 package.json。

  ¥In npm pkg set it enables parsing set values with JSON.parse() before saving them to your package.json.

并非所有 npm 命令都支持。

¥Not supported by all npm commands.

long

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

在 ls、search 和 help-search 中显示扩展信息。

¥Show extended information in ls, search, and help-search.

parseable

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

从写入标准输出的命令输出可解析的结果。对于 npm search，这将是制表符分隔的表格格式。

¥Output parseable results from commands that write to standard output. For npm search, this will be tab-separated table format.

global

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

在 "global" 模式下运行，以便将包安装到 prefix 文件夹而不是当前工作目录。有关行为差异的更多信息，请参见 文件夹。

¥Operates in "global" mode, so that packages are installed into the prefix folder instead of the current working directory. See folders for more on the differences in behavior.

• 包安装到 {prefix}/lib/node_modules 文件夹，而不是当前工作目录。

  ¥packages are installed into the {prefix}/lib/node_modules folder, instead of the current working directory.

• bin 文件链接到 {prefix}/bin

  ¥bin files are linked to {prefix}/bin

• 手册页链接到 {prefix}/share/man

  ¥man pages are linked to {prefix}/share/man

depth

• 默认值：如果设置了 --all，则为 Infinity，否则为 1

  ¥Default: Infinity if --all is set, otherwise 1

• 类型：空值或数字

  ¥Type: null or Number

为 npm ls 递归包时的深度。

¥The depth to go when recursing packages for npm ls.

如果未设置，npm ls 将仅显示根项目的直接依赖。如果设置了 --all，那么 npm 将默认显示所有依赖。

¥If not set, npm ls will show only the immediate dependencies of the root project. If --all is set, then npm will show all dependencies by default.

omit

• 默认值：'dev' 如果 NODE_ENV 环境变量设置为 'production'，否则为空。

  ¥Default: 'dev' if the NODE_ENV environment variable is set to 'production', otherwise empty.

• 类型："dev"、"optional"、"peer"（可多次设置）

  ¥Type: "dev", "optional", or "peer" (can be set multiple times)

要从磁盘上的安装树中省略的依赖类型。

¥Dependency types to omit from the installation tree on disk.

请注意，这些依赖仍会被解析并添加到 package-lock.json 或 npm-shrinkwrap.json 文件中。它们只是没有物理安装在磁盘上。

¥Note that these dependencies are still resolved and added to the package-lock.json or npm-shrinkwrap.json file. They are just not physically installed on disk.

如果一个包类型同时出现在 --include 和 --omit 列表中，那么它将被包括在内。

¥If a package type appears in both the --include and --omit lists, then it will be included.

如果生成的省略列表包含 'dev'，则 NODE_ENV 环境变量将针对所有生命周期脚本设置为 'production'。

¥If the resulting omit list includes 'dev', then the NODE_ENV environment variable will be set to 'production' for all lifecycle scripts.

include

• 默认值：

  ¥Default:

• 类型："prod"、"dev"、"optional"、"peer"（可多次设置）

  ¥Type: "prod", "dev", "optional", or "peer" (can be set multiple times)

允许定义要安装的依赖类型的选项。

¥Option that allows for defining which types of dependencies to install.

这是 --omit=<type> 的倒数。

¥This is the inverse of --omit=<type>.

--include 中指定的依赖类型将不会被忽略，无论命令行中指定省略/包含的顺序如何。

¥Dependency types specified in --include will not be omitted, regardless of the order in which omit/include are specified on the command-line.

link

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

与 npm ls 一起使用，将输出限制为仅链接的那些包。

¥Used with npm ls, limiting output to only those packages that are linked.

package-lock-only

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

如果设置为 true，当前操作将只使用 package-lock.json，忽略 node_modules。

¥If set to true, the current operation will only use the package-lock.json, ignoring node_modules.

对于 update，这意味着只会更新 package-lock.json，而不是检查 node_modules 并下载依赖。

¥For update this means only the package-lock.json will be updated, instead of checking node_modules and downloading dependencies.

对于 list，这意味着输出将基于 package-lock.json 描述的树，而不是 node_modules 的内容。

¥For list this means the output will be based on the tree described by the package-lock.json, rather than the contents of node_modules.

unicode

• 默认值：在 Windows 上为 false，在具有 unicode 区域设置的 mac/unix 系统上为 true，如 LC_ALL、LC_CTYPE 或 LANG 环境变量所定义。

  ¥Default: false on windows, true on mac/unix systems with a unicode locale, as defined by the LC_ALL, LC_CTYPE, or LANG environment variables.

• 类型：布尔值

  ¥Type: Boolean

当设置为 true 时，npm 在树输出中使用 unicode 字符。当为 false 时，它​​使用 ascii 字符而不是 unicode 字形。

¥When set to true, npm uses unicode characters in the tree output. When false, it uses ascii characters instead of unicode glyphs.

workspace

• 默认值：

  ¥Default:

• 类型：字符串（可以设置多次）

  ¥Type: String (can be set multiple times)

启用在当前项目的已配置工作区的上下文中运行命令，同时通过仅运行此配置选项定义的工作区进行过滤。

¥Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option.

workspace 配置的有效值为：

¥Valid values for the workspace config are either:

• 工作区名称

  ¥Workspace names

• 工作区目录的路径

  ¥Path to a workspace directory

• 父工作区目录的路径（将导致选择该文件夹中的所有工作区）

  ¥Path to a parent workspace directory (will result in selecting all workspaces within that folder)

为 npm init 命令设置时，可以将其设置为尚不存在的工作区的文件夹，以创建文件夹并将其设置为项目中的全新工作区。

¥When set for the npm init command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

workspaces

• 默认值：null

  ¥Default: null

• 类型：空值或布尔值

  ¥Type: null or Boolean

设置为 true 可在所有已配置工作区的上下文中运行该命令。

¥Set to true to run the command in the context of all configured workspaces.

显式将此设置为 false 将导致像 install 这样的命令完全忽略工作区。未明确设置时：

¥Explicitly setting this to false will cause commands like install to ignore workspaces altogether. When not set explicitly:

• 在 node_modules 树上运行的命令（安装、更新等）会将工作区链接到 node_modules 文件夹。* 执行其他操作（测试、执行、发布等）的命令将在根项目上运行，除非在 workspace 配置中指定了一个或多个工作区。

  ¥Commands that operate on the node_modules tree (install, update, etc.) will link workspaces into the node_modules folder. - Commands that do other things (test, exec, publish, etc.) will operate on the root project, unless one or more workspaces are specified in the workspace config.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

include-workspace-root

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

为命令启用工作区时包括工作区根。

¥Include the workspace root when workspaces are enabled for a command.

当为 false 时，通过 workspace 配置指定单个工作区，或通过 workspaces 标志指定所有工作区，将导致 npm 仅在指定的工作区上运行，而不是在根项目上运行。

¥When false, specifying individual workspaces via the workspace config, or all workspaces via the workspaces flag, will cause npm to operate only on the specified workspaces, and not on the root project.

此值不会导出到子进程的环境中。

¥This value is not exported to the environment for child processes.

install-links

• 默认值：false

  ¥Default: false

• 类型：布尔值

  ¥Type: Boolean

设置文件时：协议依赖将作为常规依赖打包和安装，而不是创建符号链接。此选项对工作区没有影响。

¥When set file: protocol dependencies will be packed and installed as regular dependencies instead of creating a symlink. This option has no effect on workspaces.

也可以看看

¥See Also

• 包定义

  ¥package spec

• npm explain

• npm config

• npmrc

• npm folders

• npm explain

• npm install

• npm link

• npm prune

• npm outdated

• npm update