1. Identify the timeout before changing Clash
When npm install stalls, retries repeatedly, or ends with an error such as ETIMEDOUT, ECONNRESET, ENETUNREACH, or socket hang up, the fastest solution is not to replace every line of your Clash configuration. First determine which connection is failing and which process owns it.
npm may contact the configured registry, download tarballs from a different host, resolve package metadata, request authentication information, and execute lifecycle scripts that make their own network calls. A browser that loads the npm website successfully proves very little because the browser may use the system proxy while your terminal uses a direct socket.
This guide assumes that you run a Clash-compatible client such as Clash Verge Rev or a Mihomo-based client. The exact menu names may differ, but the diagnostic logic is the same. You want to answer four questions: which registry is configured, whether DNS resolution works, whether the terminal can reach the Clash mixed port, and whether the selected policy group has a usable node. Do not begin by adding a large collection of guessed domain rules. A broad rule can hide the actual failure and may accidentally send private registries, internal Git servers, or corporate package mirrors through an untrusted relay.
Capture the original error before retrying. Run the command from the project directory with more detailed logging and save the output for comparison:
npm config get registry
npm config get proxy
npm config get https-proxy
npm ping --verbose
npm install --verbose
The default public registry is usually https://registry.npmjs.org/, but a project, user profile, organization policy, or environment variable may point npm somewhere else. A timeout against an internal registry requires a different fix from a timeout against the public registry. Also check whether the project contains an .npmrc file, because npm configuration is layered and a local file can override the value you changed globally.
2. Understand npm’s network path
A normal package installation is not always a single request to one hostname. npm first asks the registry for package metadata, then retrieves package archives whose URLs may be returned in the metadata response. Scoped packages can use a separate registry, and authentication settings can introduce additional requests. A package’s install script may download a prebuilt binary from GitHub Releases, a vendor CDN, or an object-storage endpoint after npm itself has already succeeded.
This explains a common pattern: npm ping works, but npm install fails halfway through. The registry is reachable, yet one tarball host, native dependency mirror, or post-install download is not. Conversely, a browser test of registry.npmjs.org can succeed while npm fails because the Node.js process is not using the same proxy settings.
There are three common traffic designs:
- System proxy mode: Clash exposes a local HTTP or mixed port, and applications that understand operating-system proxy settings send requests to it.
- Environment proxy mode: the terminal receives
HTTP_PROXY,HTTPS_PROXY, andNO_PROXYvariables, allowing command-line programs to use Clash explicitly. - TUN mode: Clash captures connections at the virtual network interface, including programs that do not understand proxy variables. TUN still depends on correct DNS handling, routing mode, permissions, and exclusions.
A terminal can bypass Clash in all three situations. The shell may have been opened before the proxy was enabled, the application may ignore system settings, or a direct route may be deliberately selected by a rule. On macOS and Linux, inspect the current environment with env | grep -i proxy. On Windows PowerShell, use Get-ChildItem Env:*proxy*. Empty output does not prove that TUN is inactive, but it does show that npm is not receiving an explicit proxy from the shell.
In Clash, open the connections or logs panel while running npm ping. Look for the actual destination, the rule that matched it, and the policy group used. If no connection appears, the process probably bypasses Clash, the request is being resolved or blocked before the expected log entry, or npm is using an unexpected registry. If a connection appears as DIRECT when you expected a proxy, the problem is likely rule order or mode selection rather than npm itself.
3. Test the terminal through the Clash port
Use a small, controlled test before repeating a large installation. In the Clash client, find the local HTTP or mixed port; common examples include 7890 or 7897, but you must use the value displayed by your client. Test the registry through that port with curl:
curl -I --max-time 20 \
-x http://127.0.0.1:7890 \
https://registry.npmjs.org/
curl -sS --max-time 20 \
-x http://127.0.0.1:7890 \
https://registry.npmjs.org/npm
A successful response such as HTTP/2 200 or HTTP/1.1 200 shows that the local proxy accepts the request and the selected Clash route can reach the registry. A connection refusal usually means the port is wrong, Clash is not running, or the local listener is restricted. A timeout after the proxy connection succeeds points toward the selected node, DNS path, remote filtering, or the destination itself.
Now compare the same request without the proxy:
curl -I --max-time 20 https://registry.npmjs.org/
If the direct request fails but the proxied request succeeds, configure npm or the shell to use the working Clash path. If both fail, check DNS, the node, and the registry status. If the direct request succeeds but the proxied request fails, do not assume that the proxy is automatically better; the selected node may be overloaded, geographically distant, or unable to resolve the registry correctly.
For a temporary npm test, use explicit configuration rather than permanently changing the user profile:
npm --proxy=http://127.0.0.1:7890 \
--https-proxy=http://127.0.0.1:7890 \
ping --verbose
npm --proxy=http://127.0.0.1:7890 \
--https-proxy=http://127.0.0.1:7890 \
install
If this works, set the values only if you want npm to use Clash consistently:
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
When you finish testing, review the saved values. A stale proxy pointing to a closed port is one of the most frequent reasons npm suddenly stops working after a client update:
npm config get proxy
npm config get https-proxy
npm config list
If you prefer environment variables, use the syntax appropriate for your shell:
# macOS or Linux
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,.local
# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,.local"
Avoid setting both conflicting npm proxy values and environment variables without documenting them. When debugging, one explicit method is easier to reason about. Also remember that a new terminal inherits environment variables only when it is opened after they are configured. IDE-integrated terminals may require closing and reopening the entire IDE, not just creating a new tab.
4. Fix Clash rules, DNS, and policy groups
Once the terminal request appears in Clash logs, inspect the decision chain. A typical configuration should place explicit private-network and internal-domain rules before broad proxy rules. Public npm traffic can use a reliable proxy group, while an organization’s private registry should remain on the company VPN or DIRECT path according to its security policy.
| Symptom | Likely cause | Useful check |
|---|---|---|
| No Clash connection is shown | npm bypasses the proxy or uses an unexpected registry | Check npm config get registry, environment variables, and TUN status |
| Local port refuses the connection | Wrong port or inactive Clash listener | Confirm the HTTP/mixed port in the client |
| Registry request is routed DIRECT and times out | Rule order or mode sends npm outside the proxy | Inspect the matched rule and policy group |
| Metadata succeeds but a package download fails | Tarball or binary host uses another domain | Read the verbose URL and inspect live connections |
| Requests work briefly, then reset | Unstable node, overloaded group, or DNS inconsistency | Switch node and compare repeated npm ping tests |
For registry traffic, an explicit domain rule is usually safer than a giant catch-all list. A representative Mihomo rule section might look like this:
rules:
- DOMAIN,registry.npmjs.org,NPM-Proxy
- DOMAIN-SUFFIX,npmjs.org,NPM-Proxy
- DOMAIN,registry.your-company.example,Corporate-VPN
- DOMAIN-SUFFIX,your-company.example,Corporate-VPN
- MATCH,Default
Replace the policy names with groups that actually exist in your profile. Do not copy this block unchanged into a production configuration. If your organization uses a private scope, verify its registry mapping in .npmrc before creating rules. A broad DOMAIN-SUFFIX,npmjs.org line may cover the public registry, but it will not automatically cover GitHub, a vendor’s release server, or an arbitrary URL returned by a package installer.
Rule order matters. If a preceding GEOIP, FINAL, or catch-all rule matches first, the later npm-specific rule never runs. Move the explicit rules above broad regional or default rules, then reload the configuration. Clear assumptions by watching the connection entry again rather than relying on the visible mode badge.
DNS can create a separate failure. With fake-IP mode, an application may receive synthetic addresses that are correctly intercepted by Clash, but some runtimes, native modules, or security software behave badly when they see non-public answers. With redirection or enhanced DNS mode, the resolver may instead return an address that is unreachable through the selected route. Test resolution from the same machine:
nslookup registry.npmjs.org
dig registry.npmjs.org
node -e "require('dns').lookup('registry.npmjs.org', console.log)"
Compare the result with and without Clash DNS handling only when your network policy permits it. If changing DNS fixes the issue, keep the change narrow and document why. Do not disable certificate verification or add insecure TLS options merely to hide a DNS or routing failure.
5. Separate node problems from npm and package problems
A proxy route can be technically correct and still be unusable. Nodes differ in latency, packet loss, congestion, TLS behavior, and access to particular hosting networks. Test the same registry request several times through two or three policy choices. A node that returns quickly once but fails intermittently during repeated requests is not suitable for dependency installation, where dozens or hundreds of connections may be opened.
Keep the test small and reproducible:
- Reload the Clash profile and confirm that the intended policy group is active.
- Run
npm ping --verbosethree times with a short pause between attempts. - Run a clean metadata request for one package, such as
npm view lodash version. - Install one known package in a temporary directory rather than inside a critical project.
- Repeat the test with a second node and compare latency, reset errors, and log entries.
If registry metadata succeeds but a specific dependency fails, inspect the package URL printed by verbose npm output. Native modules frequently fetch binaries from GitHub, release CDNs, or vendor storage. You may need a separate rule for that host, but first confirm that the package is trustworthy and that its maintainer documents the download location. Never route unknown install scripts through a relay without considering what data the script can send.
Private registries deserve special care. A common configuration uses the public registry for ordinary packages and a company registry for a scope:
registry=https://registry.npmjs.org/
@company:registry=https://packages.company.example/
//packages.company.example/:_authToken=${NPM_TOKEN}
The private hostname may need DIRECT or a corporate VPN route, while the public registry needs the Clash proxy. Do not set a global proxy rule that sends both destinations through the same third-party node. Check token exposure as well: npm debug output, shell history, and copied configuration files should not contain credentials.
If an installation fails only when lifecycle scripts run, use a controlled comparison:
npm install --ignore-scripts
npm rebuild
This is a diagnostic technique, not a universal fix. If the first command succeeds and npm rebuild fails, the registry path is probably healthy and a post-install process needs its own proxy or domain rule. Review the package documentation and the process’s environment before changing Clash globally.
6. Make the working setup maintainable
After identifying the cause, remove temporary experiments that create future ambiguity. Decide whether npm should use explicit proxy settings, environment variables, TUN capture, or a documented combination. Record the Clash local port, the policy group, the relevant registry rules, and the expected NO_PROXY entries in the project or team setup notes. Avoid committing personal proxy addresses, access tokens, or machine-specific paths to a shared repository.
Keep package-manager behavior observable. A short diagnostic script can print the active registry without exposing authentication credentials:
#!/usr/bin/env sh
set -eu
printf 'Registry: '
npm config get registry
printf 'Proxy: '
npm config get proxy
printf 'HTTPS proxy: '
npm config get https-proxy
npm ping --verbose
Run this after changing networks, upgrading Node.js, importing a new Clash profile, or switching between an office VPN and a home connection. Node and npm upgrades can alter HTTP behavior, certificate stores, connection reuse, or environment handling. A previously working configuration may therefore need a fresh test even when the YAML has not changed.
For CI, do not depend on a developer’s desktop Clash process unless the runner is intentionally configured for it. Prefer an approved corporate proxy, an internal registry mirror, or a runner-level network policy. If a CI job must use an HTTP proxy, inject credentials through the CI secret store and ensure logs redact them. A local fix that relies on 127.0.0.1:7890 will fail on a remote runner because that address refers to the runner itself.
Security should remain part of the troubleshooting process. A successful download through a proxy does not validate the package, the node operator, or an install script. Keep npm’s TLS verification enabled, use lockfiles where appropriate, review unexpected dependency changes, and avoid pasting complete verbose logs when they contain private registry URLs. The goal is reliable routing, not blind trust in every endpoint that becomes reachable.
Compared with simple VPN toggles that expose only a global on-or-off choice, Clash gives you a visible connection log, ordered domain rules, selectable nodes, and a practical way to keep public npm traffic separate from internal registries. That makes the fix easier to verify and less disruptive to Git, company services, and local development. If you are looking for a client that can apply the same controlled routing across terminal tools and desktop applications, you can continue with the Clash clients and setup options below.
Download Clash clients and start reliable package access →
Ready to get started?
Choose a Clash-compatible client, then apply predictable routing to npm, Git, and other developer tools.
Route npm and other developer tools through a tested Clash policy across Windows, macOS, Linux, and Android.
Free Download