Does npm Work in China? Registry Integrity Checklist

Does npm work in China? It can return package metadata yet fail while downloading a tarball, authenticating to a scope, checking integrity, or running local installation scripts. Diagnose the exact stage with the committed lockfile and effective registry configuration; do not treat one successful package lookup as proof of a reproducible install.

Key Takeaways:

• Preserve package.json, the lockfile, .npmrc scopes, the npm version, and the first complete error before changing configuration.
• Separate registry metadata, tarball hosts, authentication, integrity, dependency resolution, and lifecycle scripts.
• Prefer npm ci for a clean, frozen project install when a valid lockfile is committed.
• Never solve connectivity by disabling TLS or integrity checks or silently moving credentials to an unreviewed mirror.

The general mainland China service checklist covers browser and route basics. This guide focuses on npm's package-consumption chain; the China VPN guide provides the broader legal and routing context.

Does npm work in China, and which registry stage is failing?

Record the first divergent request

The public registry exposes package metadata that points to distribution tarballs, while private or scoped packages may use another registry and authentication policy. A search result, package page, or metadata response does not prove the selected tarball can be downloaded and verified.

Stage	Evidence to retain	Common non-network cause
Configuration	Effective registry and scope, with tokens removed	Project or user .npmrc override
Metadata	Package, version, status and response time	Missing version or wrong registry
Tarball	Host, byte-transfer stage and retry pattern	Stale lockfile URL or storage response
Integrity	Expected and received integrity result	Corrupt cache or changed artifact
Installation	First failing package and lifecycle phase	Native build, peer dependency or script

Redact _authToken, cookies, private package names, internal registry hosts, and usernames before sharing output. Preserve status codes and error classes so authentication is not confused with timeout or integrity failure.

1. Freeze the project and toolchain before testing

Record the Node.js and npm versions, operating system, architecture, project commit, package.json, lockfile type, and whether workspaces participate. Preserve uncommitted work and do not regenerate or delete the lockfile as a first troubleshooting step. A different lockfile can select different versions and tarball URLs, destroying the comparison.

Use an authorized project or a small disposable fixture whose dependencies and scripts you understand. Avoid repeated full installs against a production workspace. Capture the first failure from a bounded run, then classify whether it occurred before or after package bytes arrived.

If the project requires flags such as legacy-peer-deps to create its lockfile, keep the same project configuration for npm ci; npm warns that differing dependency-shaping flags can cause errors.［2］

2. Inspect the effective registry and scope configuration

Record the effective public registry, each relevant @scope:registry, proxy settings, certificate settings, and configuration source. Do not print token values. Project, user, environment, and managed configuration can disagree, and a private scope may be routed somewhere entirely different from unscoped public packages.

The npm registry documentation identifies the default public registry as https://registry.npmjs.org/ and explains that registry selection can be scope-specific.［1］ Confirm that the lockfile and configuration refer to intended, reviewed endpoints. A copied .npmrc may contain a stale internal host or a token bound to another registry.

Keep strict-ssl enabled. Do not add credentials to a new mirror until its ownership, TLS, retention, package-sync, integrity, and incident processes are approved.

3. Separate metadata lookup from tarball download

Use a documented, read-only metadata operation for an authorized public package and record the response status and timing. Then inspect the selected version's tarball host without exposing credentials. If metadata succeeds but the tarball transfer stalls, you have narrowed the path; you have not shown that npm as a whole is unavailable.

Compare one known small package and one dependency from the actual lockfile. A failure limited to a single name or version can be package state, access level, deprecation, or a missing artifact. A failure across different package metadata requests suggests a broader registry, DNS, TLS, proxy, or authentication boundary.

Do not use a browser package page as a substitute for CLI evidence. The browser, CLI, proxy, authentication, and content hosts may differ.

4. Verify authentication and scoped-package policy

Distinguish 401 or 403 responses from connection errors. Check whether the token is intended for that exact registry, still valid, permitted for the scope, authorized by the organization, and available to the current environment. In CI, confirm only the secret name and injection boundary; never print the value or upload a debug log containing it.

A public unscoped package succeeding while a private scoped package fails usually points to registry selection, token scope, organization policy, or package permission. It does not prove that the private registry route is blocked. Ask the registry or organization owner to verify access rather than copying a developer token into CI.

If authentication is successful but requests are limited, preserve response headers and reduce retries. A network route cannot raise an account or registry limit.

5. Use the lockfile and verify package integrity

For a project with an existing valid lockfile, npm ci requires that the lockfile agree with package.json, removes an existing node_modules, and does not rewrite the lockfile.［2］ Run it only after preserving local state and only where that clean-install behavior is acceptable. It provides a stronger reproducibility test than an unconstrained install that updates dependency selection.

Treat an integrity mismatch as a security and artifact-consistency signal, not an inconvenience. Preserve the package name, expected integrity value, cache state, and endpoint; stop before bypassing the check. npm documents registry signatures and audit verification for supported registry data.［3］ Use capabilities supported by the current npm version and registry, and distinguish signature availability from package vulnerability auditing.

Do not edit the integrity field, reuse an unexplained tarball, or accept a package from a look-alike name merely to finish an install.

6. Isolate cache, dependency, and lifecycle-script failures

Once all package bytes are available and verified, later failures are usually not registry reachability. Classify peer-dependency conflicts, unsupported Node versions, native addon builds, missing compilers, platform-specific optional dependencies, filesystem permissions, disk space, antivirus interference, and lifecycle scripts.

Inspect the first post-download error. Do not disable all scripts globally unless the project owner has chosen that diagnostic and understands that it changes installation behavior. Do not run unfamiliar package scripts on a privileged workstation merely to test access.

If cache corruption is plausible, use npm's documented cache verification and an approved disposable cache before destructive cleanup. Preserve the original evidence and avoid broad deletion across unrelated projects.

7. Compare one route and prove reproducibility

Hold the project commit, lockfile, npm version, configuration, account, and time window constant. If policy and applicable law permit, AethoVPN can supply the one controlled alternative path: connect the development machine to a listed location, run a clean npm ci against the same lockfile, and compare integrity results and timing with the original route. Start the 3-day AethoVPN trial on a personal machine rather than a managed build host. It changes routing only and cannot repair a lockfile, grant private-package access, satisfy organization policy, fix a native build, or validate an unknown package source.

After the narrow correction, repeat the frozen install in an approved clean environment. Record whether metadata, every tarball, integrity verification, and lifecycle execution completed, plus the resulting dependency state. Success on one laptop with a warm cache is weaker evidence than a clean, lockfile-based run.

Use the Docker Hub image checklist for container layers and the PyPI package checklist for Python distribution selection. CI-specific failures belong in the GitHub Actions runner checklist.

Summary

• Freeze the lockfile, npm version, effective configuration, and first error.
• Test metadata, tarball, authentication, integrity, and installation as separate stages.
• Use npm ci when its clean, frozen behavior is appropriate.
• Preserve TLS, credentials, source identity, and integrity guarantees.
• Confirm a clean repeatable install instead of relying on cache or a package page.

FAQ

Is the npm registry permanently unavailable in China?

Do not make a permanent country-wide conclusion from one network or package. Test the intended registry, package, version, tarball, and current time as separate evidence.

Why does npm view work while npm ci fails?

Metadata can succeed before tarball download, integrity verification, dependency resolution, or scripts fail. Identify the first package and stage that diverges.

Should I switch to a mirror immediately?

No. First verify the configured registry and failure stage. Use only an organization-approved source whose ownership, TLS, synchronization, integrity, and credential handling are understood.

Should I set strict-ssl=false?

No. A certificate error requires correction of the clock, proxy, trust store, managed certificate, or route. Disabling TLS verification exposes credentials and package content.

Does npm ci change my lockfile?

It should not write the lockfile and will fail when it does not agree with package.json. It also removes existing node_modules, so preserve any needed local state first.

Can a VPN fix an integrity mismatch?

No. An integrity mismatch concerns the expected and received artifact or cache. Stop, preserve evidence, and verify the official source instead of bypassing the check.

How do I prove npm works for my project?

Complete a clean install from the committed lockfile with the intended registry and npm version, verify all package integrity checks, and record any scripts or platform requirements.

Disclaimer: This article provides general operational and supply-chain security information, not legal, employer-policy, or service-availability advice. Follow applicable law, npm's current documentation, and your organization's package-source controls.

Sources

1. npm Docs, Registry: https://docs.npmjs.com/cli/v11/using-npm/registry
2. npm Docs, npm ci: https://docs.npmjs.com/cli/v11/commands/npm-ci/
3. npm Docs, Verifying ECDSA registry signatures: https://docs.npmjs.com/cli/v11/commands/npm-audit/#audit-signatures

Sources checked 12 September 2026.

---

Related reading:

• Best VPN for China: service-planning guide
• Apps and websites not working in mainland China
• Pulling Docker Hub images from mainland China
• Does PyPI work in China?
• Do GitHub Actions work in China?