
در فرآیند توسعه با Flutter و Dart، استفاده از پکیجها و بستهها اهمیت زیادی دارد. با این حال، در برخی مواقع ممکن است به دلیل مشکلات شبکه , پروکسی دسترسی به pub.dev (منبع اصلی پکیجها) با اختلال مواجه شود. این مشکلات میتواند ناشی از محدودیتهای اینترنتی، فایروالها یا حتی سرورهای غیرفعال باشد.
قطعا با وجود ابزار های دور زدن فیلترینگ تجربه خطاهای ناموفق عدم دانلود پکیج های فلاتری را داشتید و حسابی کلافه شدید خواستید خودتون رو از بالا پرت کنید پایین.

یک راه حل کاربردی و امتحان شده برای زمانی که نشت آی پی ایران دارید.
اگر هنگام
flutter pub getبا خطاهایی مثل Authentication error (403) یا مشکلات شبکه روبهرو میشوید، استفاده از Mirror قابلاعتماد میتواند دریافت وابستگیها را پایدارتر کند.
استفاده از یک Mirror برای pub به ما این امکان را میدهد تا به جای مراجعه به pub.dev، از یک منبع محلی یا نزدیکتر استفاده کنیم. برای این کار تنها نیاز به یک سوییچ یکفرمانی داریم که به ما اجازه میدهد تا بهراحتی به Mirror متصل شویم.
سوییچ سریع بین آینه و منبع رسمی را تنها با یک دستور خواهید داشت.

در macOS پیشفرض شل zsh است. برای اطمینان:
echo $SHELL
خروجی معمول: /bin/zsh
قبل از هر تغییری از ~/.zshrc بکاپ بگیرید:
cp ~/.zshrc ~/.zshrc.bak-$(date +%Y%m%d)
~/.zshrcبا ویرایشگر دلخواه باز کنید. مثلا با TextEdit:
open -e ~/.zshrc
یا اگر VS Code دارید:
code ~/.zshrc
این بلوک را عیناً به انتهای فایل اضافه کنید:
# >>> PUB MIRROR SWITCH >>> export PUB_HOSTED_URL="https://pub.flutter-io.cn" export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn" alias pub-cn='export PUB_HOSTED_URL="https://pub.flutter-io.cn"; export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"; echo "Using mirror: $PUB_HOSTED_URL"' alias pub-dev='export PUB_HOSTED_URL="https://pub.dev"; export FLUTTER_STORAGE_BASE_URL="https://storage.googleapis.com"; echo "Using upstream: $PUB_HOSTED_URL"' # <<< PUB MIRROR SWITCH <<<
توضیح خطوط:
PUB_HOSTED_URL: مبدأ دریافت پکیجهای Dart/Flutter.
FLUTTER_STORAGE_BASE_URL: مبدأ دریافت باینریها/آرتیفکتهای Flutter (مانند engine و SDK).
pub-cn: در همان شل فعلی سوییچ به Mirror.
pub-dev: در همان شل فعلی سوییچ به مبدأ رسمی.
برای اعمال فوری تغییرات:
source ~/.zshrc
echo $PUB_HOSTED_URL echo $FLUTTER_STORAGE_BASE_URL
انتظار در حالت Mirror:
https://pub.flutter-io.cn
https://storage.flutter-io.cn
اجرای عادی (پس از باز شدن شل جدید، Mirror پیشفرض است):
flutter pub get
سوییچ صریح به Mirror در همین ترمینال:
pub-cn flutter pub get
سوییچ به منبع رسمی در همین ترمینال:
pub-dev flutter pub get
اگر خطا ادامه داشت:
flutter clean سپس flutter pub get
سوییچ بین Mirror/رسمی: pub-cn یا pub-dev
بررسی دسترسی ها:
curl -I https://pub.dev/api/packages/archive/advisories curl -I https://pub.flutter-io.cn/api/packages/archive/advisories
این تنظیمات تضمین «صفر خطا» نیست؛ آینهها ممکن است گهگاهی کند یا در دسترس نباشند.
فایل ~/.zshrc را باز کرده و بلوک افزودهشده را پاک/کامنت کنید، سپس:
source ~/.zshrc
در صورت نیاز میتوانید بکاپ را برگردانید:
mv ~/.zshrc.bak-YYYYMMDD ~/.zshrc source ~/.zshrc
میتوانید از PowerShell (توصیهشده) یا CMD استفاده کنید. در هر دو حالت، برای دائمیکردن، متغیرهای محیطی سطح کاربر را تنظیم میکنیم.

PowerShell را بهصورت عادی باز کنید (بدون نیاز به ادمین برای سطح کاربر):
setx PUB_HOSTED_URL "https://pub.flutter-io.cn" setx FLUTTER_STORAGE_BASE_URL "https://storage.flutter-io.cn"
نکته: اثر setx در نشست فعلی دیده نمیشود؛ یک PowerShell جدید باز کنید. اگر میخواهید هماکنون هم اعمال شود:
$env:PUB_HOSTED_URL = "https://pub.flutter-io.cn" $env:FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn"
ساخت/باز کردن پروفایل:
New-Item -Type File -Path $PROFILE -Force notepad $PROFILE
این توابع را در پروفایل بچسبانید تا هر بار با باز شدن PowerShell در دسترس باشند:
function Use-PubMirror { $env:PUB_HOSTED_URL = "https://pub.flutter-io.cn" $env:FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn" Write-Host "Using mirror: $env:PUB_HOSTED_URL" } function Use-PubUpstream { $env:PUB_HOSTED_URL = "https://pub.dev" $env:FLUTTER_STORAGE_BASE_URL = "https://storage.googleapis.com" Write-Host "Using upstream: $env:PUB_HOSTED_URL" } function Set-PubMirrorPermanent { setx PUB_HOSTED_URL "https://pub.flutter-io.cn" | Out-Null setx FLUTTER_STORAGE_BASE_URL "https://storage.flutter-io.cn" | Out-Null Write-Host "User env set to MIRROR. Open a new PowerShell." } function Set-PubUpstreamPermanent { setx PUB_HOSTED_URL "https://pub.dev" | Out-Null setx FLUTTER_STORAGE_BASE_URL "https://storage.googleapis.com" | Out-Null Write-Host "User env set to UPSTREAM. Open a new PowerShell." }
بارگذاری مجدد پروفایل (یا باز کردن پنجره جدید):
. $PROFILE
در نشست فعلی:
$env:PUB_HOSTED_URL $env:FLUTTER_STORAGE_BASE_URL
مقدار دائمی (User):
[Environment]::GetEnvironmentVariable("PUB_HOSTED_URL","User") [Environment]::GetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL","User")
flutter pub get # با مقادیر دائمی Use-PubMirror # سوییچ فوری به میرور در همین نشست Use-PubUpstream # سوییچ فوری به منبع رسمی
[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", $null, "User") [Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", $null, "User")
سپس یک PowerShell جدید باز کنید.

setx PUB_HOSTED_URL "https://pub.flutter-io.cn" setx FLUTTER_STORAGE_BASE_URL "https://storage.flutter-io.cn"
یک CMD جدید باز کنید تا اثر کند.
set PUB_HOSTED_URL=https://pub.flutter-io.cn set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
یک فایل به نام pub-cn.cmd بسازید و محتوای زیر را در آن قرار دهید:
@echo off set PUB_HOSTED_URL=https://pub.flutter-io.cn set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn echo Using mirror: %PUB_HOSTED_URL%
یک فایل به نام pub-dev.cmd بسازید:
@echo off set PUB_HOSTED_URL=https://pub.dev set FLUTTER_STORAGE_BASE_URL=https://storage.googleapis.com echo Using upstream: %PUB_HOSTED_URL%
اگر مسیر این فایلها در PATH باشد، میتوانید در همان CMD اجرا کنید:
pub-cn flutter pub get pub-dev flutter pub get
echo %PUB_HOSTED_URL% echo %FLUTTER_STORAGE_BASE_URL%
setx حذف مستقیم ندارد. از PowerShell استفاده کنید:
[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", $null, "User") [Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", $null, "User")
سپس یک CMD جدید باز کنید.

خوشحالم که تا اینجا مقاله را خواندی و امیدوارم کاربردی بوده باشد.
این روش پایداری را بهتر میکند، اما تضمین ۱۰۰٪ نیست. اگر آینهها کند شدند، به منبع رسمی برگردید.
در CI/CD بهتر است متغیرها را بهطور صریح در محیط همان Job تنظیم کنید تا قابل تکرار باشد.
پس از تغییر مقادیر دائمی با setx، همیشه ترمینال جدید باز کنید.
اگر پشت پراکسی هستید، تنظیمات پراکسی سیستم/ترمینال را بررسی کنید.

می دونید که با ❤️ کردن باعث انگیزه می شوید. منتظر کامنت های شما هستم.
حتما تجربه های خودتون را در کامیونیتی فلاتر فارسی به اشتراک بگذارید.