Volta, the same problem, pitched me 3 times | 在一家公司做了 10 年的前端

type

status

date

slug

summary

category

icon

password

中文版本：

Volta，同一个问题，坑了我 3 次

For front-end development, the use of multiple versions of node is a common demand, one of the most important reasons, I feel the most deeply are the following two

Project compatibility differences: old projects rely on old versions of Node.js, upgrading the node version (some of the api's big changes lead to incompatibility) build errors, and often to solve this kind of problem is not pleasing to the effort. New projects are usually recommended to use the latest stable version ( LTS version ).

Dependency conflicts: Some of the underlying libraries (e.g., node-gyp related packages for compiling C++, e.g., the infamous node-sass ) are very sensitive to the Node version. Upgrading the global Node version directly results in the need to re-download the corresponding node version of the package for the corresponding operating system (which may run into network issues and require some magic to fix), or even download the source code and build it yourself, which can cause the npm install or build process of the project to crash, which is very frustrating.

There are also a number of open source solutions in the community for managing multiple versions of node, and I switched from nvm to volta ( https://volta.sh/). The first time I learned about volta was when I read about it in one of webstorm's changelogs, and I was a bit curious, so I went searching on the web.

volta is written by rust, and what attracted me significantly at that time was the senseless automatic switching across projects.

When I used nvm in the past, when I switched between projects, I needed to manually switch node versions, which required me to memorize or look up the node version supported by the current project, which was always a mental burden. volta has a pin node version feature.

It adds a customized section of volta to package.json.

This way, every time you switch to this project, you will use the node version that is fixed under the current project. This can be inconsistent with the global node version.

However, recently this year, because of contact with vite, found another feature of volta, resulting in the same problem, pit me 3 times, a little unacceptable is that I stepped on the pit before, but also wrote a document to record, but after 3 months, a moment of thought, visible middle-aged people's memory is indeed poor.

This feature is called Install and forget https://docs.volta.sh/guide/#features in the official documentation.

First of all, let's explain the benefits of doing this. For management tools like nvm, after switching the node version globally, the commands that were installed globally will be invalidated, and the corresponding global commands will need to be reinstalled. The feature of volta is that if you install a global command once, it will always be available. This works because each global command is bound to the version of the node it was installed on.

For example

Let's say your current global node is v 22.x.x

You install pnpm globally, and it binds to the current global node, version 22.x.x.

On a later date, when you globally switch the node to version 24, use the following command

If your project uses pnpm as a package manager, when you run pnpm dev

The project may directly or indirectly prompt you for a node version mismatch, and when you use ai or search to get some information about the compatible node version, you consciously check the node version under the current project and find that the result matches again, so you are baffled, and even if you use ai to continue, it's still a serious nonsense.

Which node is in effect?

You check the version of the node in the current project.

If the current project uses a volta pin, it's the node version of the pin, otherwise it's the global node version. This may not be the same as the version of the node bound to the pnpm installation. How to prove this is simple: create a node version checking script, check-node-version.js, and run it with pnpm to find the exact node version and the path to the node command.

The above screenshot shows a project that doesn't use the volta pin, and the node version of the pnpm command doesn't match the global node version.

The difficulty in troubleshooting is that this feature is really easy to forget. It's really in line with the official propaganda, Install and forget, it's really a success or a failure, in fact, most of this feature is really convenient, but in a few cases, when you forget, this kind of seemingly contradictory problem troubleshooting becomes a chore, which will make people fall into constant self-doubt.

Reality shows that I've been pitched this same problem 3 times, no exaggeration at all.

Let's post this recent case ( 2026-1-4 )

Recently on my Windows PC with the latest vitepress 2.x, running pnpm dev reported an error.

Asked gemini.

I ran node --version, 22.x, under project, and it was fine. Then I asked ai about it, and ai started talking nonsense.

At night when I threw out the garbage, I suddenly remembered that the node version is not correct, but the version of node is correct, but also the vite scenario, it seems to have encountered, but also wrote a document, and quickly went back to search. When I looked at the documentation, it's only been 3 months, and I ran into the same problem again.

How to Solve

Check the global node version, 22.x, no problem.

First uninstall pnpm, then reinstall pnpm

Problem solved.

Conclusion

Sometimes, when a tool does a lot of things for you, if you don't understand the underlying principles, you're bound to run into pitfalls.

After using volta to manage node and installing global pnpm with volta, when executing pnpm-related commands in a project, the node version running behind the scenes may not be consistent with the node pinned in the project or the global node.

After finishing the documentation and organizing the blog for publication, I hope I won't forget this again.