npm 中文文档

npm-check-updates


npm-check-updates upgrades your package.json dependencies to the latestversions, ignoring specified versions.

maintains existing semantic versioning policies, i.e. "react": "^16.0.4"to "react": "^18.2.0".
only* modifies package.json file. Run npm installto update your installed packages and package-lock.json.
clean output
sensible defaults
lots of options for custom behavior
CLI and module usage
compatible with npm, yarn, and pnpm

npm-check-updates-screenshot

Red = major upgrade (and all major version zero )
Cyan = minor upgrade
Green = patch upgrade

Installation


Install globally:

  1. ``` shell
  2. npm install -g npm-check-updates
  3. ```

Or run with npx :

  1. ``` shell
  2. npx npm-check-updates
  3. ```

Usage


Show all new dependencies (excluding peerDependencies) for the project in the current directory:

  1. ``` shell
  2. $ ncu
  3. Checking package.json
  4. [====================] 5/5 100%

  6. eslint             7.32.0  →    8.0.0
  7. prettier           ^2.7.1  →   ^3.0.0
  8. svelte            ^3.48.0  →  ^3.51.0
  9. typescript         >3.0.0  →   >4.0.0
  10. untildify          <4.0.0  →   ^4.0.0
  11. webpack               4.x  →      5.x

  13. Run ncu -u to upgrade package.json
  14. ```

Upgrade a project's package file:

Make sure your package file is in version control and all changes have been committed. This willoverwrite your package file.


  1. ``` shell
  2. $ ncu -u
  3. Upgrading package.json
  4. [====================] 1/1 100%

  6. express           4.12.x  →   4.13.x

  8. Run npm install to install new versions.

  10. $ npm install      # update installed packages and package-lock.json
  11. ```

Check global packages:

  1. ``` shell
  2. ncu -g
  3. ```

Filter packages using the --filteroption or adding additional cli arguments. You can exclude specific packages with the --rejectoption or prefixing a filter with !. Supports strings, wildcards, globs, comma-or-space-delimited lists, and regular expressions:

  1. ``` shell
  2. # upgrade only mocha
  3. ncu mocha
  4. ncu -f mocha
  5. ncu --filter mocha

  7. # upgrade packages that start with "react-"
  8. ncu react-*
  9. ncu "/^react-.*$/"

  11. # upgrade everything except nodemon
  12. ncu \!nodemon
  13. ncu -x nodemon
  14. ncu --reject nodemon

  16. # upgrade only chalk, mocha, and react
  17. ncu chalk mocha react
  18. ncu chalk, mocha, react
  19. ncu -f "chalk mocha react"

  21. # upgrade packages that do not start with "react-".
  22. ncu \!react-*
  23. ncu '/^(?!react-).*$/' # mac/linux
  24. ncu "/^(?!react-).*$/" # windows
  25. ```

How dependency updates are determined


Direct dependencies are updated to the latest stable version:
2.0.1→ 2.2.0
1.2→ 1.3
0.1.0→ 1.0.1

Range operators are preserved and the version is updated:
^1.2.0→ ^2.0.0
1.x→ 2.x
>0.2.0→ >0.3.0

"Less than" is replaced with a wildcard:
<2.0.0→ ^3.0.0
1.0.0 < 2.0.0→ ^3.0.0

"Any version" is preserved:
`→ `

Prerelease and deprecated versions are ignored by default.
Use --preto include prerelease versions (e.g. alpha, beta, build1235)
Use --deprecatedto include deprecated versions

With --target minor, only update patch and minor:
0.1.0→ 0.2.1

With --target patch, only update patch:
0.1.0→ 0.1.2

With --target @next, update to the version published on the nexttag:
0.1.0-> 0.1.1-next.1

Options


  1. ``` sh
  2. --cache                    Cache versions to the cache file
  3. --cacheClear               Clear the default cache, or the cache file
  4.                            specified by --cacheFile
  5. --cacheExpiration <min>    Cache expiration in minutes (default: 10)
  6. --cacheFile <path>         Filepath for the cache file (default:
  7.                            "~/.ncu-cache.json")
  8. --color                    Force color in terminal
  9. --concurrency <n>          Max number of concurrent HTTP requests to
  10.                            registry. (default: 8)
  11. --configFileName <s>       Config file name. (default: .ncurc.{json,yml,js})
  12. --configFilePath <path>    Directory of .ncurc config file. (default:
  13.                            directory of `packageFile`)
  14. --cwd <path>               Working directory in which npm will be executed.
  15. --deep                     Run recursively in current working directory.
  16.                            Alias of (--packageFile '**/package.json').
  17. --dep <value>              Check one or more sections of dependencies only:
  18.                            dev, optional, peer, prod, bundle
  19.                            (comma-delimited). (default:
  20.                            "prod,dev,bundle,optional")
  21. --deprecated               Include deprecated packages.
  22. -d, --doctor               Iteratively installs upgrades and runs tests to
  23.                            identify breaking upgrades. Requires "-u" to
  24.                            execute. Run "ncu --help --doctor" for details.
  25. --doctorInstall <command>  Specifies the install script to use in doctor
  26.                            mode. (default: npm install/yarn)
  27. --doctorTest <command>     Specifies the test script to use in doctor mode.
  28.                            (default: npm test)
  29. --enginesNode              Include only packages that satisfy engines.node as
  30.                            specified in the package file.
  31. -e, --errorLevel <n>       Set the error level. 1: exits with error code 0 if
  32.                            no errors occur. 2: exits with error code 0 if no
  33.                            packages need updating (useful for continuous
  34.                            integration). (default: 1)
  35. -f, --filter <p>           Include only package names matching the given
  36.                            string, wildcard, glob, comma-or-space-delimited
  37.                            list, /regex/, or predicate function.
  38. --filterVersion <p>        Filter on package version using
  39.                            comma-or-space-delimited list, /regex/, or
  40.                            predicate function.
  41. --format <value>           Modify the output formatting or show additional
  42.                            information. Specify one or more comma-delimited
  43.                            values: group, ownerChanged, repo. Run "ncu --help
  44.                            --format" for details. (default: [])
  45. -g, --global               Check global packages instead of in the current
  46.                            project.
  47. --groupFunction <fn>       Customize how packages are divided into groups
  48.                            when using '--format group'. Run "ncu --help
  49.                            --groupFunction" for details.
  50. -i, --interactive          Enable interactive prompts for each dependency;
  51.                            implies -u unless one of the json options are set.
  52. -j, --jsonAll              Output new package file instead of human-readable
  53.                            message.
  54. --jsonDeps                 Like `jsonAll` but only lists `dependencies`,
  55.                            `devDependencies`, `optionalDependencies`, etc of
  56.                            the new package data.
  57. --jsonUpgraded             Output upgraded dependencies in json.
  58. -l, --loglevel <n>         Amount to log: silent, error, minimal, warn, info,
  59.                            verbose, silly. (default: "warn")
  60. --mergeConfig              Merges nested configs with the root config file
  61.                            for --deep or --packageFile options. (default:
  62.                            false)
  63. -m, --minimal              Do not upgrade newer versions that are already
  64.                            satisfied by the version range according to
  65.                            semver.
  66. --packageData <value>      Package file data (you can also use stdin).
  67. --packageFile <path|glob>  Package file(s) location. (default:
  68.                            ./package.json)
  69. -p, --packageManager <s>   npm, yarn, staticRegistry (default: npm). Run "ncu
  70.                            --help --packageManager" for details.
  71. --peer                     Check peer dependencies of installed packages and
  72.                            filter updates to compatible versions. Run "ncu
  73.                            --help --peer" for details.
  74. --pre <n>                  Include prerelease versions, e.g. -alpha.0,
  75.                            -beta.5, -rc.2. Automatically set to 1 when
  76.                            --target is newest or greatest, or when the
  77.                            current version is a prerelease. (default: 0)
  78. --prefix <path>            Current working directory of npm.
  79. -r, --registry <uri>       Third-party npm registry. Run "ncu --help
  80.                            --registry" for details.
  81. -x, --reject <p>           Exclude packages matching the given string,
  82.                            wildcard, glob, comma-or-space-delimited list,
  83.                            /regex/, or predicate function.
  84. --rejectVersion <p>        Exclude package.json versions using
  85.                            comma-or-space-delimited list, /regex/, or
  86.                            predicate function.
  87. --removeRange              Remove version ranges from the final package
  88.                            version.
  89. --retry <n>                Number of times to retry failed requests for
  90.                            package info. (default: 3)
  91. --root                     Runs updates on the root project in addition to
  92.                            specified workspaces. Only allowed with
  93.                            --workspace or --workspaces. (default: false)
  94. -s, --silent               Don't output anything. Alias for --loglevel
  95.                            silent.
  96. --stdin                    Read package.json from stdin.
  97. -t, --target <value>       Determines the version to upgrade to: latest,
  98.                            newest, greatest, minor, patch, @[tag], or
  99.                            [function]. (default: latest) Run "ncu --help
  100.                            --target" for details.
  101. --timeout <ms>             Global timeout in milliseconds. (default: no
  102.                            global timeout and 30 seconds per
  103.                            npm-registry-fetch)
  104. -u, --upgrade              Overwrite package file with upgraded versions
  105.                            instead of just outputting to console.
  106. --verbose                  Log additional information for debugging. Alias
  107.                            for --loglevel verbose.
  108. -w, --workspace <s>        Run on one or more specified workspaces. Add
  109.                            --root to also upgrade the root project. (default:
  110.                            [])
  111. -ws, --workspaces          Run on all workspaces. Add --root to also upgrade
  112.                            the root project.
  113. -V, --version              output the version number
  114. -h, --help                 display help for command

  116. ```

Interactive Mode


Choose exactly which upgrades to make in interactive mode:

  1. ``` shell
  2. ncu --interactive
  3. ncu -i
  4. ```

Select which upgrades you want:

ncu --interactive

Combine with --format groupfor a truly luxeexperience:

ncu --interactive --format group

Doctor Mode


Usage: ncu --doctor [-u] [options]

Iteratively installs upgrades and runs tests to identify breaking upgrades. Requires -uto execute (modifies your package file, lock file, and node_modules).

To be more precise:

Runs npm install(or yarn) and npm testto ensure tests are currently passing. You can specify your own scripts with --doctorInstalland --doctorTest.
Runs ncu -uto optimistically upgrade all dependencies.
If tests pass, hurray!
If tests fail, restores package file and lock file.
For each dependency, install upgrade and run tests.
When the breaking upgrade is found, saves partially upgraded package.json (not including the breaking upgrade) and exits.

Example:

  1. ``` shell
  2. $ ncu --doctor -u
  3. npm install
  4. npm run test
  5. ncu -u
  6. npm install
  7. npm run test
  8. Failing tests found:
  9. /projects/myproject/test.js:13
  10.   throw new Error('Test failed!')
  11.   ^
  12. Now let's identify the culprit, shall we?
  13. Restoring package.json
  14. Restoring package-lock.json
  15. npm install
  16. npm install --no-save react@16.0.0
  17. npm run test
  18.   ✓ react 15.0.0 → 16.0.0
  19. npm install --no-save react-redux@7.0.0
  20. npm run test
  21.   ✗ react-redux 6.0.0 → 7.0.0
  22. Saving partially upgraded package.json
  23. ```

Config File


Use a .ncurc.{json,yml,js}file to specify configuration information. You can specify file name and path using --configFileNameand --configFilePathcommand line options.

For example, .ncurc.json:

  1. ``` json
  2. {
  3.   "upgrade": true,
  4.   "filter": "svelte",
  5.   "reject": ["@types/estree", "ts-node"]
  6. }
  7. ```

Module/Programmatic Usage


npm-check-updates can be imported as a module:

  1. ``` js
  2. import ncu from 'npm-check-updates'

  4. const upgraded = await ncu.run({
  5.   // Pass any cli option
  6.   packageFile: '../package.json',
  7.   upgrade: true,
  8.   // Defaults:
  9.   // jsonUpgraded: true,
  10.   // silent: true,
  11. })

  13. console.log(upgraded) // { "mypackage": "^2.0.0", ... }
  14. ```

Contributing


Contributions are happily accepted. I respond to all PR's and can offer guidance on where to make changes. For contributing tips see CONTRIBUTING.md .

Known Issues


If ncuprints output that does not seem related to this package, it may be conflicting with another executable such as ncu-weather-clior Nvidia CUDA. Try using the long name instead: npm-check-updates.
Windows: If npm-check-updates hangs, try setting the package file explicitly: ncu --packageFile package.json. You can run ncu --loglevel verboseto confirm that it was incorrectly waiting for stdin. See #136 .

Problems?


File an issue . Please search existing issues first.