Start Here: Identify Which Connection Is Failing
An npm install timeout while Clash is running does not automatically mean the proxy is broken. npm may be reaching the wrong registry, trying to use a proxy that is not listening, following a Clash rule that sends registry traffic DIRECT, or waiting for a DNS lookup to finish. A dependency can also come from a different host than the npm registry, so a successful connection to one domain does not prove the whole installation path is available.
The useful first question is not “Is Clash on?” but “At which step does the request stop?” A failure such as ETIMEDOUT usually means a connection did not complete in time. ECONNREFUSED often means a configured proxy address or port has no listener. EAI_AGAIN points toward a temporary name-resolution problem, while ENOTFOUND suggests that the hostname could not be resolved. These clues are not absolute diagnoses, but they help narrow the next test.
npm installation may contact the registry for package metadata and tarballs, then contact other hosts for packages referenced by lockfiles or dependencies. Private registries, Git URLs, and packages hosted on a content delivery network add more possible routes. Keep the full error output, especially the failing URL and error code, before changing settings. It can tell you whether the timeout involves registry.npmjs.org, a custom registry, a proxy endpoint, or an unrelated dependency host.
A Good Diagnostic Rule
Change one variable at a time. Testing the registry, proxy, and DNS separately is faster and safer than switching several Clash settings at once.
1Check the npm Registry and Clash Route
Start by checking which registry npm is configured to use. In a terminal, run:
The usual public npm registry is https://registry.npmjs.org/. Your project, user-level .npmrc, environment, or a company setup may specify a different URL. Do not replace an organization’s private registry with the public one without checking first: private package names may only exist on the configured service, and sending them elsewhere can expose package names or credentials.
To test the currently configured registry without installing packages, run:
If npm ping responds but an install still stalls, the registry’s basic endpoint is reachable, but a tarball host, package-specific route, or local configuration may still be failing. If it times out, copy the registry URL from npm config get registry and test that exact host. For a temporary comparison against the public registry, you can run npm ping --registry=https://registry.npmjs.org/. This command does not permanently rewrite your configuration.
Next, inspect the route in your Clash client. In Clash Verge, Clash Verge Rev, or another Mihomo-based client, make sure the proxy is running and look at the connection or log view while running npm ping. Find the registry hostname and note which rule and policy group handled it. In Rule mode, a matching DOMAIN-SUFFIX or DOMAIN rule may send traffic to DIRECT, a selected proxy group, or another policy. A rule that is correct for a browser is not necessarily correct for a terminal if the terminal is not using the same system proxy or TUN route.
For a quick comparison, test both the current route and a known working proxy node. If the registry fails only through one node, the problem may be node reachability, filtering, or a slow route rather than npm itself. If it succeeds DIRECT but fails through the proxy, inspect the selected node and the rule group. If it succeeds through the proxy but not DIRECT, your local network may be blocking or poorly routing the registry. Use a rule-specific adjustment only when it matches your network needs; avoid switching the entire configuration to Global mode as a permanent fix.
2Inspect Proxy Settings in the Terminal
Clash’s system proxy setting generally configures applications that honor the operating system’s proxy settings. Command-line tools do not all do that. Depending on the platform, shell, and npm version, npm may instead rely on its own configuration or environment variables. That is why a browser can work through Clash while npm install times out.
Check npm’s saved proxy values and the current shell environment. Use the commands for your terminal:
Look for stale values such as a port from an older proxy application, a hostname that no longer exists, or a proxy URL that uses the wrong protocol. A common local Clash mixed port is 7890, but the port is configurable and may be different in your profile. Check the actual port shown in the client settings rather than copying an example blindly. Also distinguish between an HTTP proxy endpoint and a SOCKS endpoint: configuring an HTTP proxy URL against a SOCKS-only port, or the reverse, can cause immediate connection failures.
If your Clash client exposes a local HTTP or mixed port, test it with the endpoint and port configured on your machine. For example, when the HTTP listener is available at 127.0.0.1:7890, you can temporarily test:
These are diagnostic examples, not universal port settings. If the test works only after setting the variables, the terminal was not using the Clash listener before. If it still fails, confirm that the listener is enabled, that the address and port match, and that the selected Clash policy can reach the registry. Do not expose a local proxy listener to your LAN unless you intentionally need that access and have secured it.
When you set proxy variables in PowerShell, they remain in that terminal session until you close it or remove them. To clear the temporary values, run Remove-Item Env:HTTP_PROXY and Remove-Item Env:HTTPS_PROXY. In macOS or Linux shells, use unset HTTP_PROXY HTTPS_PROXY. If you use a persistent shell profile, check that it is not restoring outdated values every time a new terminal opens.
Do Not Disable TLS Verification
Avoid setting strict-ssl=false to “fix” a timeout. It weakens certificate checks and does not repair an unreachable registry, mismatched proxy, or bad route.
3Run a Controlled Install Test
Use this sequence to separate a project-specific issue from a general connection problem. Run each test from a terminal where you can see the output. Do not delete your lockfile or clear all npm configuration before collecting evidence; those actions can change dependency resolution and make the original failure harder to reproduce.
- Record the active setup. Run
node --version,npm --version,npm config get registry, and the proxy inspection commands above. Note whether Clash is in Rule or Global mode, which node is selected, and whether TUN mode is enabled. - Test the registry without installing. Run
npm pingandnpm view npm version --fetch-retries=0. If either fails, save the exact code and URL instead of repeatedly retrying. - Observe Clash’s connection log. While repeating one test, confirm whether the registry hostname appears. No matching connection can indicate that the terminal is bypassing the system proxy and TUN route, or that the request is failing before Clash sees it. A logged connection marked
DIRECTor assigned to an unexpected group points toward rule selection. - Compare a known route. Choose a working node in Clash, then repeat the same registry test. Keep the registry URL and npm command unchanged so the route is the only variable. If your network permits a direct connection, compare that as a separate test rather than changing multiple rules at once.
- Retry a small, known package. In a temporary directory, run
npm init -yand thennpm install is-number --verbose. This helps determine whether the failure occurs generally or only in the original project. The verbose output can reveal whether metadata or a package tarball is the request that stalls.
Interpret the results as a comparison, not as a pass/fail verdict from one command. If the small install works but the project install does not, examine the project’s .npmrc, lockfile URLs, scoped registries, private packages, and Git dependencies. If both fail at the same registry request, focus on npm’s registry, the terminal’s proxy path, and Clash routing. If the registry tests work but package downloads fail, inspect the specific tarball hostname shown in verbose output and verify that its route is permitted too.
For a more useful error report, repeat a failing command once with --verbose and note the timestamp, request hostname, and error code. Redact authentication tokens, private registry credentials, internal hostnames, and sensitive project names before sharing logs. A long stack trace without the failing URL is usually less helpful than a short record of the exact request and the route Clash selected.
4Check DNS, Rules, and Safe Recovery
If the error is EAI_AGAIN or ENOTFOUND, investigate name resolution before changing npm retry counts. Confirm that the hostname in the error is spelled correctly and that it is the expected registry or package host. In Clash, check that DNS is enabled and that the DNS mode and upstream servers are appropriate for your network. With TUN mode enabled, DNS handling can differ from ordinary system-proxy mode, so change DNS settings only after verifying that DNS is actually the failing step.
Compare the same hostname through a second network or a different Clash node when possible. If the lookup fails on every route, the problem may be local DNS, an invalid hostname, or an unavailable upstream resolver. If it resolves but the connection times out, DNS is probably not the main obstacle; continue checking the selected rule, proxy listener, and node. After any DNS change, repeat the same command and hostname so the result remains comparable.
Review custom rules that could catch npm traffic. A broad DOMAIN-KEYWORD rule, a private-domain rule, or a general GEOIP rule may route traffic differently than expected. The connection log is the best way to confirm the actual match. Prefer a narrow rule for the required registry or dependency domain over a broad rule that affects unrelated traffic. Remember that a lockfile may contain download URLs on a separate host; routing only registry.npmjs.org may not cover every package source.
If npm has an obsolete proxy saved in its configuration, remove only the value you have confirmed is wrong. For example, npm config delete proxy and npm config delete https-proxy remove npm-level entries, but a project or user .npmrc may still define them. Inspect the relevant configuration files and environment variables before assuming the setting is gone. Likewise, avoid clearing the npm cache as a first response: cached package data is rarely the cause of a network timeout, and a cache clean does not correct a routing problem.
Once the route works, retry the original install with the same lockfile. If the failure was intermittent, a modest retry setting can help with transient registry interruptions, but it should not hide a persistent connectivity issue. Do not set excessively long timeouts to compensate for a dead proxy or blocked hostname. Keep a short note of the working registry, proxy mode, listener port, and Clash policy so you can distinguish future node outages from configuration changes.
Before You Finish
Verify the registry, confirm the terminal’s proxy path, watch the matching Clash rule, and test the exact host named in the error. Remove temporary environment variables when the test is complete.