# UnblockNeteaseMusic/server: reviving greyed-out songs in Netease Cloud Music

> A proxy that swaps unavailable tracks for copies pulled from other music services. It is aimed at people who already run their own Netease Cloud Music client and are willing to operate a local server.

**UnblockNeteaseMusic/server** — Revive unavailable songs for Netease Cloud Music (Refactored & Enhanced version)

- Repository: https://github.com/UnblockNeteaseMusic/server
- Stars: 7,839 · Forks: 762
- Language: JavaScript
- License: LGPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/unblockneteasemusic-server

## What UnblockNeteaseMusic/server actually does

The README states the project's purpose plainly: it unlocks greyed-out songs in the Netease Cloud Music client. A greyed-out track is one the client lists but will not play, usually because the rights for that region or that period have lapsed. The project does not restore those rights. It intercepts the client's request for the track and answers with audio fetched from a different service, so the client receives a playable URL where it expected a failure.

That framing matters for who this is for. It is not a downloader and not a music library. It is a man-in-the-middle proxy that sits between the Netease client and Netease's servers, plus a set of adapters for other providers. The people who get value from it are users who already have a Netease Cloud Music account, already run something on their own machine or router, and want the client's own interface to keep working. Anyone expecting a standalone player will be disappointed: without the client, the proxy has nothing to serve.

## The proxy mechanism and the source list

The README describes three capabilities. It replaces greyed-out track links with links from other sources. It adds an X-Real-IP parameter to requests to get around overseas restrictions, with options to pin a specific Netease server IP and to route through an upstream HTTP or HTTPS proxy. And it provides full HTTP/HTTPS traffic proxying, usable as a system proxy with PAC support.

The source list is the part that determines what you actually hear. The README's table gives each provider a short code passed through -o. kugou, bodian, migu and ytdlp are enabled by default. qq, kuwo, joox, youtube, youtubedl, bilibili, bilivideo and pyncmd are not. Several carry conditions: qq needs your own QQ_COOKIE and a QQ login, migu needs MIGU_COOKIE, joox needs JOOX_COOKIE and only covers Hong Kong, Macau, Thailand, Malaysia and Indonesia, youtube needs an IP address Google treats as outside mainland China, youtubedl needs youtube-dl installed, and ytdlp needs yt-dlp installed. The README notes the pyncmd API service is provided by GD studio at music.gdstudio.xyz, and that bilivideo may fail to find certain licensed videos from outside mainland China.

The design choice here is worth naming. Rather than scraping one service well, the project keeps a roster of adapters with different authentication and geography requirements, and lets the operator order them. That is flexible, and it is also the source of most of the support burden: a failure is usually one adapter's problem, not the proxy's.

## Installing and running it from npm

The README lists several routes. The quickest for a machine with Node is the published package. The package.json declares engines.node as >= 12, and the binary entry point is precompiled/app.js exposed as unblockneteasemusic.

Install it as a dependency, or skip installation entirely with npx:

```bash
npm install @unblockneteasemusic/server
yarn add @unblockneteasemusic/server # for Yarn users
```

```bash
npx -p @unblockneteasemusic/server unblockneteasemusic
```

Running the binary starts the proxy. The README's help output shows the flags: -p for the port, -a for the address, -u for an upstream proxy URL, -f to force a Netease server IP, -o to set source priority, -t for proxy authentication, -e to replace the virtual endpoint, -s for strict mode, and -c for a mainland China relay. To prefer Bilibili and yt-dlp over the defaults, the README gives this example:

```bash
node app.js -o bilibili ytdlp
```

After that, point the Netease client or your system proxy at the address the server is listening on. The README's Windows service section states the HTTP proxy uses 127.0.0.1 with default port 8080, and the docker-compose.yml maps 8080 and 8081 by default through HTTP_PROXY_PORT and HTTPS_PROXY_PORT.

## Running it in Docker, or from a clone

The Docker image is published as pan93412/unblock-netease-music-enhanced. The README says latest is built from the enhanced branch and release is the newest tag. The plain run command needs no arguments:

```bash
docker run pan93412/unblock-netease-music-enhanced
```

Environment variables go in with -e, and server flags go after the image name. Both forms appear in the README:

```bash
docker run -e JSON_LOG=true -e LOG_LEVEL=debug pan93412/unblock-netease-music-enhanced
docker run pan93412/unblock-netease-music-enhanced -o kuwo -p 1234
```

The repository's own Dockerfile is worth reading before you build. It starts from node:lts-alpine, installs python3 and youtube-dl from apk, downloads the latest yt-dlp release into /usr/local/bin, and writes an /etc/yt-dlp.conf pointing the cache at /var/cache/yt-dlp and the JS runtime at the container's node binary. It copies precompiled/* plus the certificate and key into /app, sets SIGN_CERT, SIGN_KEY and NODE_ENV, exposes 8080 and 8081, and uses node app.js as the entrypoint. In other words the image assumes the precompiled bundle exists, which is why the README's self-build path runs docker-compose up from a clone rather than a bare docker build.

For a plain clone, the README gives git clone, cd, then node app.js, with a note suggesting screen or tmux to keep it running. Updating is git pull. To build the latest package, run yarn then yarn build before node app.js; to use the latest package without compiling, the README shows DEVELOPMENT=true yarn node app.js.

## Where the proxy stops being the right tool

The most obvious limitation is that this is a proxy, not a client patch. If your Netease Cloud Music build ignores system proxy settings, or pins its own endpoints, nothing here helps until you find another way to route its traffic. The README does not document rollback or uninstall beyond one line about running node ./nw.js again to remove the Windows service, so plan for that before you install it as a service.

Source quality is the second limit, and it is uneven by design. Each adapter depends on a third party staying online and unchanged. The README's own notes concede this: youtube needs an IP Google considers outside mainland China, bilivideo may miss licensed videos outside the mainland, joox is restricted to five markets, and qq requires a QQ login with your own cookie. A source that worked last month can stop answering without the proxy changing at all.

There is also a legal and ethical boundary the README does not discuss, and it should not be glossed over. The project routes playback through services you may not have an account with, and some adapters ask you to supply cookies from accounts you do have. That is a decision the operator makes, not a technical detail. If you need a service with a support contract, a stable catalogue, or permission from rights holders, this is the wrong tool. The same applies if you are not willing to run and update a local process indefinitely, because the moment it stops, the greyed-out tracks go back to being greyed out.

## How it differs from the Xposed and LuCI routes

The README points to several sibling projects rather than trying to cover every platform itself. For Android there is the 杜比大喇叭 β version Xposed module, which hooks the client in-process instead of proxying its traffic. For OpenWrt there is luci-app-unblockneteasemusic, which packages the same idea as a router plugin. For BetterNCM users there is RevivedUnblockInstaller.

The difference is architectural. An Xposed module patches the client's own request path, so there is no proxy to configure and no certificate to trust, but it only works on rooted Android devices with that framework installed. The LuCI plugin runs on the router, so every device on the network benefits without per-device setup, at the cost of running Node on hardware with limited memory. This repository is the general-purpose server: it runs anywhere Node runs, which is why the README offers npm, npx, Docker, a Windows service and a bare clone. Choose it when you want one implementation across desktop operating systems; choose the router plugin when you want the whole household covered once.

## Licence and the cost of keeping it running

The repository ships COPYING and COPYING.LESSER, and package.json declares the licence as LGPL-3.0-only. The practical consequence for most users is nil, since they run the proxy rather than redistribute it. It matters if you embed the package in another product or ship a modified build: LGPL-3.0-only carries obligations about source availability and about allowing relinking, and the exact scope depends on how you combine it. That is a question for a lawyer, not for this article.

Upgrade cost is real but modest. The package is on npm, so npm install or npx picks up new versions, and the Docker image is pulled with docker pull pan93412/unblock-netease-music-enhanced followed by a fresh run. Clones update with git pull, and the README distinguishes the built package from the raw source via yarn build and the DEVELOPMENT=true flag. The dependency list is small for a project of this scope: node-windows, pino and pino-pretty at runtime. The maintenance risk sits in the adapters, not the dependencies. When a provider changes its API, the fix arrives as a new release, and until it does, that source returns nothing.

## Conclusion

Adopt it if you already run your own Netease Cloud Music client, are comfortable pointing a system or client proxy at 127.0.0.1:8080, and accept that some sources need your own cookies or an installed yt-dlp. Do not adopt it if you need a supported, vendor-backed service, if you cannot supply a non-mainland IP for the youtube source, or if you object to routing playback through third-party services. Before committing, verify which sources answer for the tracks you actually listen to by running node app.js -o with your own order, and check whether your client honours the proxy settings the README describes.

## FAQ

### What is UnblockNeteaseMusic/server and what does it do?

It is a proxy server that replaces greyed-out Netease Cloud Music tracks with links from other music services, so the client can play them. The README also describes adding an X-Real-IP parameter to get around overseas restrictions and full HTTP/HTTPS proxying usable as a system proxy.

### How do I install UnblockNeteaseMusic/server?

The README lists several routes: install the npm package @unblockneteasemusic/server, run it without installing via npx -p @unblockneteasemusic/server unblockneteasemusic, use the Docker image pan93412/unblock-netease-music-enhanced, or clone the repository and run node app.js. Prebuilt executables are on the Releases page, though the README notes macOS binaries are not provided because of signing.

### Which music sources does UnblockNeteaseMusic/server support?

The README's table lists qq, kugou, kuwo, bodian, migu, joox, youtube, youtubedl, ytdlp, bilibili, bilivideo and pyncmd. kugou, bodian, migu and ytdlp are enabled by default, and the rest are selected by passing their codes to the -o flag.

### Does UnblockNeteaseMusic/server need cookies or extra tools?

Some sources do. The README says qq requires your own QQ_COOKIE and a QQ login, migu requires MIGU_COOKIE, joox requires JOOX_COOKIE, youtubedl requires youtube-dl installed, and ytdlp requires yt-dlp installed.

### What licence is UnblockNeteaseMusic/server under?

package.json declares the licence as LGPL-3.0-only, and the repository includes COPYING and COPYING.LESSER files. Running the proxy locally is different from redistributing a modified build, which brings the licence's relinking and source-availability conditions into play.

## Sources

- [Issues](https://github.com/UnblockNeteaseMusic/server/issues)
- [License: LGPL-3.0](https://github.com/UnblockNeteaseMusic/server/blob/enhanced/LICENSE)
- [README](https://github.com/UnblockNeteaseMusic/server/blob/enhanced/README.md)
- [Releases](https://github.com/UnblockNeteaseMusic/server/releases)
- [UnblockNeteaseMusic/server on GitHub](https://github.com/UnblockNeteaseMusic/server)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/unblockneteasemusic-server