Note: I am a junior high school student from China, and my English proficiency is limited. This issue was written with the assistance of DeepSeek. I have carefully reviewed the content to ensure it accurately represents my thoughts and requests. Thank you for your understanding.
Description
What kind of issue is this?
This is a feature request to significantly improve the package download experience for users in regions with poor network connectivity to registry.platformio.org (especially users in Mainland China).
The Critical Need for a China-Accessible Mirror
For developers in Mainland China, accessing registry.platformio.org is often extremely slow, unstable, or even completely blocked. The platform's core packages, toolchains, and SDKs (which can be 100 to 500 MB) can take hours to download or fail repeatedly, making the development process nearly impossible. This is not a minor inconvenience—it is a critical barrier that prevents many developers from using PlatformIO at all.
Currently, there is no official mirror server located within Mainland China. All traffic must cross international gateways, which are subject to severe bandwidth limitations and active interference. Establishing an official mirror in China, or at minimum allowing users to configure custom mirrors, is essential for the PlatformIO ecosystem to grow in one of the world's largest developer communities.
Evidence: Real-World Testing from China
Test 1: Browser Access – Entry Page Works, But Large Files Fail
Screenshot 1 (attached) shows normal browser access to registry.platformio.org. The entry HTML page (2 KB) loads quickly (~80 ms). However, the actual platform resources are served from cdn.registry.platformio.org. The core JavaScript file main.62578fb.js (660 KB) often downloads incompletely with Firefox error NS_ERROR_NET_PARTIAL_TRANSFER.
Screenshot 2 (attached) shows a failed attempt. The same JS file shows NS_ERROR_NET_PARTIAL_TRANSFER, with only 304 KB of 660 KB downloaded. This is a classic symptom of GFW interference—large files get truncated mid-transfer.
Key finding: The entry page (small file) can load, but large files are consistently disrupted. This is exactly the problem PlatformIO faces when downloading toolchains and libraries.
Test 2: Command Line – Ping Has No Response
Run the command:
ping registry.platformio.org
Output shows:
PING lb1.platformio.org (88.198.170.159) 56(84) bytes of data.
And then no response for over 2 minutes. The server at 88.198.170.159 (Hetzner, Germany) is effectively unreachable via ICMP from this location.
Test 3: DNS Resolution – Google DNS vs Cloudflare DNS
Run:
nslookup registry.platformio.org 8.8.8.8
This receives no response at all, requiring manual interrupt (Ctrl+C).
Run:
nslookup registry.platformio.org 1.1.1.1
Output:
Server: 1.1.1.1
Address: 1.1.1.1#53
Non-authoritative answer:
registry.platformio.org canonical name = lb1.platformio.org.
Name: lb1.platformio.org
Address: 88.198.170.159
Cloudflare DNS (1.1.1.1) works and resolves to 88.198.170.159. This confirms DNS is not the root cause—the problem is the network path to the resolved IP.
Test 4: No IPv6 Support
Run:
nslookup -type=AAAA registry.platformio.org 1.1.1.1
Output:
Server: 1.1.1.1
Address: 1.1.1.1#53
Non-authoritative answer:
*** Can't find registry.platformio.org: No answer
This confirms that registry.platformio.org has no AAAA record (IPv6).
Test 5: Real-Time Instability
During the writing of this issue, the author personally experienced https://registry.platformio.org switching from "accessible" to "completely unreachable" within minutes. This demonstrates that GFW interference is dynamic and real-time, not a simple "blocked or unblocked" state.
Current Problems Summary
-
Extremely slow / unstable downloads: Large files are frequently truncated mid-transfer (NS_ERROR_NET_PARTIAL_TRANSFER / ERR_INCOMPLETE_CHUNKED_ENCODING). The browser test above shows 660 KB JS files failing; PlatformIO toolchains (100 MB+) face the same issue.
-
No resume support: If a download fails or is interrupted, PlatformIO starts over from 0%. This is devastating for large packages.
-
No built-in mirror configuration: Users cannot configure a custom registry URL. The registry URL appears to be hardcoded.
-
Browser vs CLI inconsistency: Browser access may appear "working" for the entry page, but the pio CLI tool fails on large file downloads. This suggests room for improvement in the tool's networking stack.
-
No IPv6 support: registry.platformio.org has no AAAA record. IPv6 often experiences less GFW interference, especially on CERNET (China's education network).
-
DNS interference: Even basic DNS queries to certain foreign resolvers (Google 8.8.8.8) can be disrupted.
-
Inconsistent proxy support: The pio CLI does not always fully respect system HTTP_PROXY/HTTPS_PROXY environment variables.
-
The root cause: The Great Firewall (GFW):
- Bandwidth throttling on cross-border connections
- TCP connection resets (RST packets)
- Large file truncation (
PARTIAL_TRANSFER errors)
- DNS interference
- Dynamic blocking—works one minute, fails the next
Proposed Solutions (Prioritized)
Highest Priority
-
Establish an official mirror server in Mainland China
This would fundamentally solve the problem. Major tech companies and universities in China operate high-speed mirror services (e.g., Tsinghua TUNA, Aliyun, Huawei Cloud, USTC).
Recommended starting point: university-operated mirrors (TUNA, USTC) have lower cooperation barriers.
Why this matters: Content hosted within Mainland China bypasses GFW entirely.
-
Allow user-configurable registry host URL
Users should be able to set a custom mirror URL via platformio.ini, global config, or VSCode settings. This is the foundation for community or enterprise mirrors.
Why this approach works: Lessons from gh-proxy
A project called gh-proxy is a well-known solution among Chinese developers. It provides a simple proxy service that accelerates GitHub releases, archives, and raw file downloads by prefixing a proxy URL to the original GitHub link. One of the public instances is https://gh-proxy.com/. For example:
https://gh-proxy.com/https://github.com/xxx/xxx
This project has gained significant popularity in China, with many forks, derivatives, and public instances. Its success proves two important points:
- The community is willing and able to build acceleration services when a clear entry point is provided.
- A simple URL-based proxy mechanism is technically sufficient to bypass network interference.
If PlatformIO allows users to configure a custom registry URL, it is very likely that the community will create similar proxy services specifically for registry.platformio.org. These services could be hosted within Mainland China or on faster international routes, providing reliable high-speed downloads without requiring PlatformIO to navigate China's complex network regulations alone.
This approach gives users flexibility, encourages community innovation, and avoids the need for PlatformIO to make long-term commitments to any single provider in a region with unpredictable network policies.
High Priority
-
Support resume (continue) for interrupted downloads
Implement HTTP Range header support so that partial downloads can resume from where they left off. Critical for users with unstable connections (GFW interference is unpredictable).
-
Support speed testing and automatic mirror selection
Add a --test-mirrors flag to pio pkg install. The tool would test available mirrors and automatically select the fastest one.
Medium Priority
-
Add IPv6 (AAAA record) support
IPv6 often experiences less GFW interference. This would significantly help users on CERNET and mobile networks.
-
Improve proxy compatibility
Ensure pio CLI fully respects system HTTP_PROXY/HTTPS_PROXY environment variables. Provide clear proxy configuration options in VSCode plugin UI.
-
Provide a UI configuration entry in VSCode plugin
Allow users to configure mirror URL, proxy, and network options directly in VSCode settings.
-
Add --verbose download logs
Print the actual download URL being used for debugging.
Low Priority / Backup
- Support offline import of dependencies
Allow users to manually download .tar.gz files and import them as a 100% reliable fallback.
A Real-World Scenario: What a Developer Actually Experiences
Step 1: Creating a New Project
A developer in China runs pio project init --board esp32-s3-devkitc-1 in VSCode. PlatformIO begins installing Python dependencies via pip.
Current situation: pip downloads from PyPI are slow. The developer manually configures pip to use a Chinese mirror (Tsinghua TUNA) and Python packages install in seconds.
The issue: pip is fast, but that's just the beginning.
Step 2: Installing the Platform and Libraries
PlatformIO proceeds to download the platform itself (e.g., espressif32). This includes toolchains and SDKs totaling 100–500 MB. Then the developer's platformio.ini declares a library dependency like moononournation/GFX Library for Arduino.
Current situation: PlatformIO reaches out to https://registry.platformio.org/. The download starts at 20 KB/s. After 20 minutes, it reaches 60% and fails with a connection reset error—a classic sign of GFW interference. The entire download restarts from 0%. This cycle repeats over several hours. The developer gives up.
Step 3: With the Proposed Features
- PlatformIO runs a speed test (
--test-mirrors) and automatically selects the fastest mirror—perhaps Tsinghua TUNA at 8 MB/s.
- PlatformIO downloads the
espressif32 platform from the selected mirror. Since it's hosted within Mainland China, GFW interference is bypassed entirely. If the network drops at 70%, PlatformIO resumes from 70% instead of restarting.
- The 100 MB toolchain completes in minutes, not hours. The developer focuses on coding, not wrestling with downloads. Setup time drops from a full day to less than 10 minutes.
Potential Mirror Providers in China
Several well-established, high-speed mirror services operate within Mainland China and could potentially host PlatformIO packages:
| Provider |
Mirror URL |
Notes |
| Tsinghua TUNA |
https://mirrors.tuna.tsinghua.edu.cn/ |
Most popular, reliable academic mirror |
| Aliyun |
https://mirrors.aliyun.com/ |
Enterprise-grade, very stable |
| Huawei Cloud |
https://mirrors.huaweicloud.com/ |
Enterprise-grade, strong stability |
| USTC |
https://mirrors.ustc.edu.cn/ |
Well-established academic mirror |
| NetEase |
http://mirrors.163.com/ |
Long-standing, stable mirror |
Note: These mirrors currently host PyPI, Ubuntu, Docker, and other open-source packages. University-operated mirrors (TUNA, USTC) are recommended as a starting point due to lower cooperation barriers.
Supporting References
Attachments
Two screenshots are attached to this issue:
- Screenshot 1 – Browser access showing normal entry page load but failed large file transfer (
NS_ERROR_NET_PARTIAL_TRANSFER on main.62578fb.js).
- Screenshot 2 – Browser access failure state showing the same file truncated mid-transfer.
Please refer to the attached images for visual evidence of the NS_ERROR_NET_PARTIAL_TRANSFER issue.
Conclusion
These improvements would benefit not only users in China but also anyone in regions with unstable internet connections. The lack of a China-accessible mirror is a critical barrier preventing widespread adoption of PlatformIO in one of the world's largest developer markets.
I hope the PlatformIO team can prioritize these features. I am happy to help test or provide more details if needed.
By the way, I don't check GitHub very often. If there is any progress, you are welcome to reach out to me via email at 3835906088@qq.com or lileyanhandsome@gmail.com. Thank you!
Description
What kind of issue is this?
This is a feature request to significantly improve the package download experience for users in regions with poor network connectivity to
registry.platformio.org(especially users in Mainland China).The Critical Need for a China-Accessible Mirror
For developers in Mainland China, accessing
registry.platformio.orgis often extremely slow, unstable, or even completely blocked. The platform's core packages, toolchains, and SDKs (which can be 100 to 500 MB) can take hours to download or fail repeatedly, making the development process nearly impossible. This is not a minor inconvenience—it is a critical barrier that prevents many developers from using PlatformIO at all.Currently, there is no official mirror server located within Mainland China. All traffic must cross international gateways, which are subject to severe bandwidth limitations and active interference. Establishing an official mirror in China, or at minimum allowing users to configure custom mirrors, is essential for the PlatformIO ecosystem to grow in one of the world's largest developer communities.
Evidence: Real-World Testing from China
Test 1: Browser Access – Entry Page Works, But Large Files Fail
Screenshot 1 (attached) shows normal browser access to
registry.platformio.org. The entry HTML page (2 KB) loads quickly (~80 ms). However, the actual platform resources are served fromcdn.registry.platformio.org. The core JavaScript filemain.62578fb.js(660 KB) often downloads incompletely with Firefox errorNS_ERROR_NET_PARTIAL_TRANSFER.Screenshot 2 (attached) shows a failed attempt. The same JS file shows
NS_ERROR_NET_PARTIAL_TRANSFER, with only 304 KB of 660 KB downloaded. This is a classic symptom of GFW interference—large files get truncated mid-transfer.Key finding: The entry page (small file) can load, but large files are consistently disrupted. This is exactly the problem PlatformIO faces when downloading toolchains and libraries.
Test 2: Command Line – Ping Has No Response
Run the command:
Output shows:
And then no response for over 2 minutes. The server at
88.198.170.159(Hetzner, Germany) is effectively unreachable via ICMP from this location.Test 3: DNS Resolution – Google DNS vs Cloudflare DNS
Run:
This receives no response at all, requiring manual interrupt (Ctrl+C).
Run:
Output:
Cloudflare DNS (
1.1.1.1) works and resolves to88.198.170.159. This confirms DNS is not the root cause—the problem is the network path to the resolved IP.Test 4: No IPv6 Support
Run:
Output:
This confirms that
registry.platformio.orghas no AAAA record (IPv6).Test 5: Real-Time Instability
During the writing of this issue, the author personally experienced
https://registry.platformio.orgswitching from "accessible" to "completely unreachable" within minutes. This demonstrates that GFW interference is dynamic and real-time, not a simple "blocked or unblocked" state.Current Problems Summary
Extremely slow / unstable downloads: Large files are frequently truncated mid-transfer (
NS_ERROR_NET_PARTIAL_TRANSFER/ERR_INCOMPLETE_CHUNKED_ENCODING). The browser test above shows 660 KB JS files failing; PlatformIO toolchains (100 MB+) face the same issue.No resume support: If a download fails or is interrupted, PlatformIO starts over from 0%. This is devastating for large packages.
No built-in mirror configuration: Users cannot configure a custom registry URL. The registry URL appears to be hardcoded.
Browser vs CLI inconsistency: Browser access may appear "working" for the entry page, but the
pioCLI tool fails on large file downloads. This suggests room for improvement in the tool's networking stack.No IPv6 support:
registry.platformio.orghas no AAAA record. IPv6 often experiences less GFW interference, especially on CERNET (China's education network).DNS interference: Even basic DNS queries to certain foreign resolvers (Google
8.8.8.8) can be disrupted.Inconsistent proxy support: The
pioCLI does not always fully respect systemHTTP_PROXY/HTTPS_PROXYenvironment variables.The root cause: The Great Firewall (GFW):
PARTIAL_TRANSFERerrors)Proposed Solutions (Prioritized)
Highest Priority
Establish an official mirror server in Mainland China
This would fundamentally solve the problem. Major tech companies and universities in China operate high-speed mirror services (e.g., Tsinghua TUNA, Aliyun, Huawei Cloud, USTC).
Recommended starting point: university-operated mirrors (TUNA, USTC) have lower cooperation barriers.
Why this matters: Content hosted within Mainland China bypasses GFW entirely.
Allow user-configurable registry host URL
Users should be able to set a custom mirror URL via
platformio.ini, global config, or VSCode settings. This is the foundation for community or enterprise mirrors.Why this approach works: Lessons from
gh-proxyA project called
gh-proxyis a well-known solution among Chinese developers. It provides a simple proxy service that accelerates GitHub releases, archives, and raw file downloads by prefixing a proxy URL to the original GitHub link. One of the public instances ishttps://gh-proxy.com/. For example:https://gh-proxy.com/https://github.com/xxx/xxxThis project has gained significant popularity in China, with many forks, derivatives, and public instances. Its success proves two important points:
If PlatformIO allows users to configure a custom registry URL, it is very likely that the community will create similar proxy services specifically for
registry.platformio.org. These services could be hosted within Mainland China or on faster international routes, providing reliable high-speed downloads without requiring PlatformIO to navigate China's complex network regulations alone.This approach gives users flexibility, encourages community innovation, and avoids the need for PlatformIO to make long-term commitments to any single provider in a region with unpredictable network policies.
High Priority
Support resume (continue) for interrupted downloads
Implement HTTP Range header support so that partial downloads can resume from where they left off. Critical for users with unstable connections (GFW interference is unpredictable).
Support speed testing and automatic mirror selection
Add a
--test-mirrorsflag topio pkg install. The tool would test available mirrors and automatically select the fastest one.Medium Priority
Add IPv6 (AAAA record) support
IPv6 often experiences less GFW interference. This would significantly help users on CERNET and mobile networks.
Improve proxy compatibility
Ensure
pioCLI fully respects systemHTTP_PROXY/HTTPS_PROXYenvironment variables. Provide clear proxy configuration options in VSCode plugin UI.Provide a UI configuration entry in VSCode plugin
Allow users to configure mirror URL, proxy, and network options directly in VSCode settings.
Add
--verbosedownload logsPrint the actual download URL being used for debugging.
Low Priority / Backup
Allow users to manually download
.tar.gzfiles and import them as a 100% reliable fallback.A Real-World Scenario: What a Developer Actually Experiences
Step 1: Creating a New Project
A developer in China runs
pio project init --board esp32-s3-devkitc-1in VSCode. PlatformIO begins installing Python dependencies via pip.Current situation: pip downloads from PyPI are slow. The developer manually configures pip to use a Chinese mirror (Tsinghua TUNA) and Python packages install in seconds.
The issue: pip is fast, but that's just the beginning.
Step 2: Installing the Platform and Libraries
PlatformIO proceeds to download the platform itself (e.g.,
espressif32). This includes toolchains and SDKs totaling 100–500 MB. Then the developer'splatformio.inideclares a library dependency likemoononournation/GFX Library for Arduino.Current situation: PlatformIO reaches out to
https://registry.platformio.org/. The download starts at 20 KB/s. After 20 minutes, it reaches 60% and fails with a connection reset error—a classic sign of GFW interference. The entire download restarts from 0%. This cycle repeats over several hours. The developer gives up.Step 3: With the Proposed Features
--test-mirrors) and automatically selects the fastest mirror—perhaps Tsinghua TUNA at 8 MB/s.espressif32platform from the selected mirror. Since it's hosted within Mainland China, GFW interference is bypassed entirely. If the network drops at 70%, PlatformIO resumes from 70% instead of restarting.Potential Mirror Providers in China
Several well-established, high-speed mirror services operate within Mainland China and could potentially host PlatformIO packages:
https://mirrors.tuna.tsinghua.edu.cn/https://mirrors.aliyun.com/https://mirrors.huaweicloud.com/https://mirrors.ustc.edu.cn/http://mirrors.163.com/Supporting References
Attachments
Two screenshots are attached to this issue:
NS_ERROR_NET_PARTIAL_TRANSFERonmain.62578fb.js).Please refer to the attached images for visual evidence of the
NS_ERROR_NET_PARTIAL_TRANSFERissue.Conclusion
These improvements would benefit not only users in China but also anyone in regions with unstable internet connections. The lack of a China-accessible mirror is a critical barrier preventing widespread adoption of PlatformIO in one of the world's largest developer markets.
I hope the PlatformIO team can prioritize these features. I am happy to help test or provide more details if needed.
By the way, I don't check GitHub very often. If there is any progress, you are welcome to reach out to me via email at 3835906088@qq.com or lileyanhandsome@gmail.com. Thank you!