Construction of project front-end development environment

Introduction to tool

Node.js

Node.js is an open source, cross-platform JavaScript runtime environment. It is based on the V8 engine used by Chrome, allowing JavaScript to be executed in 运行环境 outside the browser.

Node.js can be used not only to develop Web service-side programs, but also to build front-end engineering tools, command-line tools, automated scripts, etc. Modern front-end projects often rely on Node.js to run build tools, install dependencies, and start development servers.

V8 will use 编译技术 such as just-in-time compilation to execute JavaScript. Compared to the traditional 脚本语言 execution method that interprets line by line, this type of optimization can improve the 运行速度 of the code and help the team reduce the 开发成本 caused by repeated tool chains.

npm

npm is a commonly used package manager in the Node.js ecosystem. When installing Node.js, npm is usually installed at the same time, so it is generally not necessary to install it separately.

npm not only connects to the registry for the 在线提供开源 Node.js software package, but also provides command-line tools to do the following tasks:

• Install and manage project dependencies according to package.json.
• Use package-lock.json to lock dependency resolution results to improve installation consistency in different environments.
• Execute scripts defined in package.json, such as npm run dev.
• Publish and maintain npm software packages.

Yarn, pnpm and cnpm are all related to the npm ecosystem, but their positioning is not exactly the same. Yarn and pnpm are optional package managers, and cnpm is a client compatible with the way npm is used. They should not be simply understood as “domestic mirrors of npm.” A project should try to unify the package manager and submit the corresponding lock file to avoid dependency differences after mixing.

NVM for Windows

NVM for Windows is a Node.js version management tool on the Windows platform. It can install and switch multiple Node.js versions on the same computer.

The main uses include:

• Install, uninstall, and view different versions of Node.js.
• Switch Node.js versions according to project requirements.
• Set the current version of Node.js in effect.
• Reduce the cost of compatibility between multiple projects with different Node.js versions.

Note: Windows uses NVM for Windows. It is not the same project as nvm commonly used on macOS and Linux. There are differences in installation methods and some commands.

Installation plan description

It is recommended to use NVM for Windows to install and manage Node.js uniformly. It is not recommended to install the stand-alone version of Node.js before installing NVM for Windows. When two installations exist at the same time, node -v may still display the old version after nvm use is switched due to conflicts between environment variables or installation directories.

The version of Node.js used in this project is 22.17.0. 14.20.0 is also demonstrated in the course screenshots. This version is only used for version switching exercises when compatibility with old projects is needed and should not be used as the default version for current projects.

Clean up old environment

When you have installed Node.js or NVM for Windows, it is recommended to clean up the old environment first; you can skip this section for a new computer.

Step 1: Close the relevant program

Close terminals, IDEs, development servers and other related processes that are using Node.js to avoid files being occupied.

Step 2: Record the current environment

Open a command prompt and execute the following command:

node -v
npm -v
where node
where npm

The where command can help confirm which directory the system actually calls the executable file.

Step 3: Uninstall the old version of Node.js

Uninstall the stand-alone installation of Node.js in Windows Settings or Control Panel, and then check if there are still any remnants in the original installation directory.

If you plan to use NVM for Windows in the future, especially make sure that the original Node.js physical directory does not occupy the symbolic link location of NVM. Before deleting a directory, you should first confirm that there are no configurations or files in it that need to be preserved.

Step 4: Uninstall the old version of NVM for Windows

When you need to reinstall NVM for Windows, you can uninstall it through Windows ‘application uninstall feature. After unloading, check whether failed configurations still remain in NVM_HOME, NVM_SYMLINK and PATH.

Don’t directly delete unfamiliar environment variables. Make sure that the variable points to the old NVM installation directory before cleaning up.

Step 5: Handle npm residues

You can first use the following command to view npm’s cache and global installation directory:

npm config get cache
npm config get prefix

After confirming that the old environment is no longer needed, clean up the corresponding directory. .npmrc in the user directory may contain images, agents, or private warehouse configurations and should be backed up before deleting them.

Install NVM for Windows

Step 1: Run the installer

Run the NVM for Windows installer provided by your team or course. It is recommended to use the default directory during installation; when modifying the directory, avoid the path containing special characters and ensure that there are no physical folders with the same name in the symbolically linked directory.

If the installer asks whether to take over existing Node.js, it is recommended to exit the installation first, uninstall the stand-alone version of Node.js as above and then reinstall it to avoid path conflicts.

Step 2: Re-open the terminal

After installation is complete, turn off and reopen Command Prompt or PowerShell. When switching Node.js versions, Windows usually requires administrator privileges, so it is recommended to open the terminal as an administrator.

Verify NVM for Windows by executing the following command:

nvm version

Some older versions also support:

nvm -v

Install and switch Node.js versions

Install the current project version

Execute the following command to install Node.js required by this project:

nvm install 22.17.0

Switch to this version after installation is complete:

nvm use 22.17.0

If Windows pops up a permission confirmation window during switching, the operation should be allowed after confirming that the command source is correct.

Verify current version

Execute the following command:

nvm current
node -v
npm -v

You can also view all installed versions of Node.js on this machine:

nvm list

Older versions of NVM for Windows are also available:

nvm ls

The versions with an asterisk in the list are the currently effective versions.

Example of switching old project versions

Install Node.js 14.20.0 only if an old project explicitly requires this version:

nvm install 14.20.0

You can switch and view versions after installation:

nvm use 14.20.0
nvm list

After processing the old project is completed, switch back to the current project version:

nvm use 22.17.0

Launch front-end projects

Step 1: Enter the project catalog

Open the command prompt or IDE terminal and enter the webui directory of the project:

cd <项目目录>\webui

Step 2: Confirm the Node.js version

node -v
npm -v

Current projects should use Node.js 22.17.0. If the version is incorrect, execute:

nvm use 22.17.0

Step 3: Install project dependencies

When you run a project for the first time or when dependencies change, you need to install dependencies first.

When the project has been submitted and the package-lock.json has not been modified, the reusable installation command can be used first:

npm ci

If there is no package-lock.json, or if the lock file needs to be updated, use:

npm install

Don’t randomly mix npm, Yarn, and pnpm in the same project, otherwise multiple lock files may be generated at the same time and inconsistent dependent versions may be created.

Step 4: Start the development server

npm run dev

After successful startup, the address output by the terminal shall prevail. The default address for a Vite project is usually:

http://localhost:5173

If the 5173 port is occupied, the development server may automatically select another port, so don’t judge whether the boot was successful based on the fixed address.

Troubleshooting common problems

nvm use executed successfully, but the Node.js version remained unchanged

Check the following items in turn:

• Re-open the terminal as an administrator.
• Close the old terminal window and then re-verify.
• Execute where node and check whether there are path conflicts in the stand-alone version of Node.js.
• Run nvm debug to view the issues detected by NVM for Windows.
• Make sure that the symbolic link directory of NVM is not occupied by the entity directory with the same name.

Prompt that node or npm cannot be found

Implement first:

nvm list
nvm use 22.17.0

Then close and reopen the terminal. If it still fails, check NVM_HOME, NVM_SYMLINK and PATH.

npm install or npm ci failed

Key inspections:

• Whether the current version of Node.js meets the project requirements.
• Whether package.json is consistent with package-lock.json.
• Whether the command is executed in the correct webui directory.
• Whether the network, proxy, mirror, and private warehouse authentication configurations are valid.
• Whether lock files generated by different package managers are mixed.

npm run dev prompt script does not exist

Open package.json and verify whether dev is defined in scripts. npm run dev is just a script to execute project declarations, and not all front-end projects use this command permanently.