راه‌اندازی Mirror برای Flutter/Dart Pub

مسئله چیست؟

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

قطعا با وجود ابزار های دور زدن فیلترینگ تجربه خطاهای ناموفق عدم دانلود پکیج های فلاتری را داشتید و حسابی کلافه شدید خواستید خودتون رو از بالا پرت کنید پایین.

یک راه حل کاربردی و امتحان شده برای زمانی که نشت آی پی ایران دارید.

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

راهکار بهصورت خلاصه

استفاده از یک Mirror برای pub به ما این امکان را میدهد تا به جای مراجعه به pub.dev، از یک منبع محلی یا نزدیکتر استفاده کنیم. برای این کار تنها نیاز به یک سوییچ یکفرمانی داریم که به ما اجازه میدهد تا بهراحتی به Mirror متصل شویم.

سوییچ سریع بین آینه و منبع رسمی را تنها با یک دستور خواهید داشت.

macOS + zsh — پیکربندی دائمی با توضیحات مرحلهبهمرحله

1) بررسی شل فعال

• در macOS پیشفرض شل zsh است. برای اطمینان:

echo $SHELL

خروجی معمول: /bin/zsh

2) پشتیبانگیری از تنظیمات فعلی شل

• قبل از هر تغییری از ~/.zshrc بکاپ بگیرید:

cp ~/.zshrc ~/.zshrc.bak-$(date +%Y%m%d)

3) باز کردن فایل تنظیمات ~/.zshrc

• با ویرایشگر دلخواه باز کنید. مثلا با TextEdit:

open -e ~/.zshrc

یا اگر VS Code دارید:

code ~/.zshrc

4) افزودن Mirror + سوییچ سریع

• این بلوک را عیناً به انتهای فایل اضافه کنید:

# >>> 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: در همان شل فعلی سوییچ به مبدأ رسمی.

5) بارگذاری مجدد تنظیمات

• برای اعمال فوری تغییرات:

source ~/.zshrc

6) راستیآزمایی مبدأها

echo $PUB_HOSTED_URL 
echo $FLUTTER_STORAGE_BASE_URL

انتظار در حالت Mirror:

• https://pub.flutter-io.cn

• https://storage.flutter-io.cn

7) استفادهٔ روزمره

• اجرای عادی (پس از باز شدن شل جدید، Mirror پیشفرض است):

flutter pub get

• سوییچ صریح به Mirror در همین ترمینال:

pub-cn
flutter pub get

• سوییچ به منبع رسمی در همین ترمینال:

pub-dev
flutter pub get

8) نکات و رفع اشکال سریع

اگر خطا ادامه داشت:

• 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

• این تنظیمات تضمین «صفر خطا» نیست؛ آینهها ممکن است گهگاهی کند یا در دسترس نباشند.

9) بازگردانی/حذف تغییرات(اختیاری)

• فایل ~/.zshrc را باز کرده و بلوک افزودهشده را پاک/کامنت کنید، سپس:

source ~/.zshrc

• در صورت نیاز میتوانید بکاپ را برگردانید:

mv ~/.zshrc.bak-YYYYMMDD ~/.zshrc
source ~/.zshrc

Windows — پیکربندی دائمی + سوییچ سریع

میتوانید از PowerShell (توصیهشده) یا CMD استفاده کنید. در هر دو حالت، برای دائمیکردن، متغیرهای محیطی سطح کاربر را تنظیم میکنیم.

گزینه PowerShell (پیشنهادی)

1) تنظیم دائمی (User) به آینه

• 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"

2) افزودن توابع سوییچ سریع به پروفایل PowerShell

• ساخت/باز کردن پروفایل:

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

3) راستیآزمایی

• در نشست فعلی:

$env:PUB_HOSTED_URL
$env:FLUTTER_STORAGE_BASE_URL

• مقدار دائمی (User):

[Environment]::GetEnvironmentVariable("PUB_HOSTED_URL","User")
[Environment]::GetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL","User")

4) استفادهٔ روزمره

flutter pub get        # با مقادیر دائمی
Use-PubMirror         # سوییچ فوری به میرور در همین نشست
Use-PubUpstream       # سوییچ فوری به منبع رسمی

5) بازگردانی/حذف مقادیر دائمی(اختیاری)

[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", $null, "User")
[Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", $null, "User")

سپس یک PowerShell جدید باز کنید.

گزینه Command Prompt (CMD)

1) تنظیم دائمی (User) به Mirror

setx PUB_HOSTED_URL "https://pub.flutter-io.cn"
setx FLUTTER_STORAGE_BASE_URL "https://storage.flutter-io.cn"

یک CMD جدید باز کنید تا اثر کند.

2) تنظیم موقت در همان نشست

set PUB_HOSTED_URL=https://pub.flutter-io.cn
set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

3) سوییچ سریع با فایلهای batch (اختیاری)

• یک فایل به نام 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

4) راستیآزمایی

echo %PUB_HOSTED_URL%
echo %FLUTTER_STORAGE_BASE_URL%

5) بازگردانی/حذف مقادیر دائمی(اختیاری)

• setx حذف مستقیم ندارد. از PowerShell استفاده کنید:

[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", $null, "User")
[Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", $null, "User")

سپس یک CMD جدید باز کنید.

خوشحالم که تا اینجا مقاله را خواندی و امیدوارم کاربردی بوده باشد.

نکات مهم

• این روش پایداری را بهتر میکند، اما تضمین ۱۰۰٪ نیست. اگر آینهها کند شدند، به منبع رسمی برگردید.

• در CI/CD بهتر است متغیرها را بهطور صریح در محیط همان Job تنظیم کنید تا قابل تکرار باشد.

• پس از تغییر مقادیر دائمی با setx، همیشه ترمینال جدید باز کنید.

• اگر پشت پراکسی هستید، تنظیمات پراکسی سیستم/ترمینال را بررسی کنید.

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