خطای npm و pip و Docker در ایران: عیب‌یابی با یک مهارت Claude Code

ساعت یازده شب است و پروژه باید فردا تحویل شود. npm install روی یک بسته گیر کرده، pip install وسط دانلود قطع می‌شود و docker pull جواب ۴۰۳ می‌دهد؛ همان خطای npm و pip و Docker در ایران که بیشتر برنامه‌نویس‌های ایرانی دست‌کم یک بار دیده‌اند. واکنش معمول این است که VPN را برای کل سیستم روشن کنید یا نشانی یک میرور را از کانال تلگرامی کپی کنید. هر دو ممکن است اوضاع را بدتر کنند: پراکسی‌ای که روشن می‌ماند و بقیهٔ ابزارها را هم خراب می‌کند، دستوری که بررسی گواهی TLS را خاموش می‌کند، یا مخزن بسته‌ای که نمی‌دانید چه کسی پشتش است.

مهارت «برنامه‌نویسی با اینترنت ایران» برای همین لحظه است. این خطاها را دستیار برنامه‌نویسی‌تان (مثلاً Claude Code) اول دسته‌بندی می‌کند: DNS، اتصال، TLS، کد HTTP، سهمیه یا سیاست منطقه‌ای سرویس. بعد یک تغییر کوچک و برگشت‌پذیر فقط برای همان ابزار پیشنهاد می‌دهد، با دستور برگرداندنش، و پیش از دست زدن به هر تنظیمی اجازه می‌گیرد.

عیب‌یابی خطای npm و pip و Docker در ایران با کمک دستیار

مهارت (Skill) پوشه‌ای از دستورالعمل است که دستیار فقط وقتی درخواست شما به آن مربوط باشد بازش می‌کند. اگر با این مفهوم آشنا نیستید، تفاوت Skill و MCP را بخوانید. این مهارت سرور MCP نیست و دادهٔ زنده نمی‌آورد. کارش این است که دستیار مثل یک برنامه‌نویس باتجربه و محتاط رفتار کند.

قاعدهٔ اولش ساده است: پیش از هر تغییری، تشخیص. دستیار دستور دقیق، نشانی، متن کامل خطا، سیستم‌عامل و اینکه سایت‌های دیگر باز می‌شوند یا نه را ثبت می‌کند. نوع اینترنت (مثلاً موبایل یا ثابت) را هم اگر خودتان بگویید یادداشت می‌کند. از یک درخواست ناموفق نتیجه نمی‌گیرد که سرویسی در کل کشور بسته است.

برای اینکه وقت و توکن هدر نرود، مهارت برای خودش سقف هم گذاشته است:

• در یک کار معمولی حداکثر سه میزبان بیرونی را آزمایش می‌کند.
• جست‌وجوی وب فقط یک بار، و فقط وقتی نسخه یا سیاست تازهٔ یک سرویس جواب را عوض کند.
• یک اقدام پیشنهادی می‌دهد و حداکثر یک راه جایگزین.
• اگر سه آزمون پشت سر هم علت‌ها را از هم جدا نکرد، می‌ایستد و از شما می‌پرسد.

اسکریپت کوچکی هم کنار مهارت هست که فقط با HTTPS دسترسی به چند سرویس را می‌سنجد و چیزی را در سیستم عوض نمی‌کند. دستیار آن را فقط با اجازهٔ شما اجرا می‌کند. اسکریپت با bash نوشته شده، پس در ویندوز به یک پوستهٔ bash نیاز دارید.

چرا docker pull از ایران خطای ۴۰۳ می‌دهد؟

جواب کوتاه: از یک ۴۰۳ نمی‌شود فهمید. راهنمای عیب‌یابی مهارت برای ۴۰۳ چند علت ممکن را کنار هم می‌گذارد: سیاست منطقه‌ای سرویس، قاعدهٔ امنیتی یا CDN، مشکل احراز هویت و فیلترینگ. و صریح می‌گوید این کد به‌تنهایی برای گفتن «تحریم» یا «فیلتر» کافی نیست. برای همین دستیار پیش از هر پیشنهادی متن پاسخ را می‌خواند و صفحهٔ رسمی وضعیت سرویس را نگاه می‌کند.

کدهای دیگر هم معنی جدا دارند و مهارت آن‌ها را با هم قاطی نمی‌کند:

دربارهٔ API سرویس‌های هوش مصنوعی هم مهارت مرز روشنی می‌کشد. اگر سرویسی می‌گوید منطقهٔ شما پشتیبانی نمی‌شود، این قاعدهٔ واقعی خود سرویس است. تونل نشانی IP خروجی را عوض می‌کند، ولی شرط حساب، پرداخت یا قرارداد را برآورده نمی‌کند. مهارت به دستیار می‌گوید اطلاعات موقعیت یا حساب را جعل نکند و کلید API را هرگز در ربات تلگرامی یا پراکسی ناشناس نگذارد.

میرور ایرانی npm و pip و Docker: کدام را امتحان کنیم؟

مهارت فهرستی از ۲۲ میرور ایرانی نامزد دارد، از مخزن‌های بستهٔ npm و pip تا جایگزین‌های Docker Hub که حدود ۹ مورد از آن‌هاست. نکتهٔ مهم این است که سازنده همهٔ آن‌ها را «آزموده‌نشده» علامت زده و در خود فایل نوشته این‌ها نامزدند، نه تأیید اینکه نشانی امروز کار می‌کند یا برای پروژهٔ شما مناسب است.

پس جواب «میرور داکر ایران کدام است؟» در این مهارت یک نام ثابت نیست. روش کار این است:

1. دستیار اول مسیر رسمی را امتحان می‌کند و صفحهٔ وضعیت سرویس را می‌بیند.
2. اگر مسیر رسمی کار نکرد، از فهرست نامزدها یکی را از اینترنت خود شما می‌سنجد. باز شدن صفحه یا جواب دادن DNS هنوز به این معنی نیست که میرور سالم است؛ باید همان بسته یا ایمیجی را که لازم دارید درست برگرداند.
3. تنظیم را در سطح پروژه یا کاربر می‌گذارد، نه برای کل سیستم، و پیش از آن از فایل تنظیمات نسخهٔ پشتیبان می‌گیرد.
4. دستور برگرداندن را هم کنار پیشنهاد می‌نویسد.

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

وقتی pip install قطع می‌شود: گزارشی که از دستیار می‌گیرید

فرض کنید از دستیار بخواهید علت قطع شدن نصب بستهٔ پایتون را پیدا کند و تا وقتی علت روشن نشده، به تنظیمات دست نزند. جوابی که با این مهارت می‌گیرید قالب ثابتی دارد:

• شواهد: نتیجهٔ هر آزمون با زمانش (DNS، اتصال، TLS، کد HTTP، زمان دانلود)، بدون توکن، نشانی اشتراک VPN یا نشانی IP شما.
• علت محتمل و میزان اطمینان: یکی از چهار درجه، از «تأییدشده» تا «آزموده‌نشده»، همراه با توضیح‌هایی که هنوز رد نشده‌اند.
• تغییر پیشنهادی: یک تغییر برای همان ابزار، که فقط پس از تأیید شما انجام می‌شود.
• راه برگشت: دستوری که وضعیت را به حالت قبل برمی‌گرداند.
• محدودیت‌ها و گزینهٔ بعدی: اگر این راه جواب نداد، قدم بعدی چیست.

مهارت چند کار را هم صریحاً ممنوع کرده است: خاموش کردن بررسی گواهی (مثل curl -k)، اعتماد به مخزن با گزینهٔ --trusted-host، اجرای اسکریپت دانلودی با دسترسی root بدون خواندنش، و فرستادن کد خصوصی به ربات‌ها. اضافه کردن یک مخزن دوم با --extra-index-url را هم به خاطر خطر «سردرگمی وابستگی» (dependency confusion) هشدار می‌دهد.

آماده‌سازی پروژه برای قطعی اینترنت و کار آفلاین

وقتی اینترنت بین‌الملل کامل قطع شود، هیچ VPN یا پراکسی راه دوری مسیر را برنمی‌گرداند و مهارت این را پنهان نمی‌کند. کاری که می‌شود کرد آمادگی پیش از قطعی است، و اگر به دستیار بگویید چند روز اینترنت محدود در پیش دارید، سراغ همین می‌رود:

• گیت: یک بستهٔ git bundle از شاخه‌ها و برچسب‌هایی که لازم دارید.
• داکر: ایمیج‌های پایه را از قبل بگیرید و با docker save نگه دارید (بعداً docker load)، با digest دقیق، نه فقط برچسب.
• پایتون: پوشه‌ای از فایل‌های wheel مخصوص همان سیستم‌عامل و نسخهٔ پایتون، و نصب با --no-index --find-links.
• نود: گرم کردن کش npm. خود مهارت هشدار می‌دهد این کش تضمینی برای کار کامل آفلاین نیست و باید پیش از قطعی حالت --offline را آزمود.
• بقیه: go mod vendor، وابستگی‌های Cargo، کش Gradle و Maven و Android SDK، و نسخهٔ مشخص مدل‌های Hugging Face.

برای دانلودهای بزرگ هم قاعده این است که فایل نیمه‌کاره را دور نریزید، اگر سرور اجازه بدهد از همان‌جا ادامه دهید (مثل curl -C -) و در پایان checksum را با مقدار رسمی مقایسه کنید. سازنده این‌ها را الگو می‌داند، نه دستوری که بی‌فکر اجرا شود؛ دستیار پیش از تغییر تنظیمات ساخت پروژه با شما هماهنگ می‌کند.

نصب مهارت در Claude Code

در Claude Code نصب یک دستور است. همین دستور در صفحهٔ مهارت هم آمده است:

git clone https://github.com/moeinforoughi/iran-dev-skill ~/.claude/skills/iran-dev-environment

1. دستور را در ترمینال اجرا کنید. نام پوشه باید دقیقاً iran-dev-environment باشد، چون راهنمای مخزن می‌گوید نام پوشه با name داخل SKILL.md یکی باشد. دستور بالا همین را رعایت می‌کند.
2. برنامهٔ Claude Code را ببندید و دوباره باز کنید.
3. در یک گفتگوی تازه مشکل شبکه‌تان را با متن دقیق خطا بنویسید و بخواهید پیش از هر تغییری علت را پیدا کند.

قالب مهارت استاندارد باز است و سازنده آن را قابل‌حمل معرفی می‌کند. اگر برنامهٔ دیگری دارید، پوشه را طبق مستندات همان برنامه در محل مهارت‌ها بگذارید و نامش را عوض نکنید. مثل هر مهارتی که از منبع بیرونی می‌گیرید، پیش از نصب فایل‌هایش را یک بار بخوانید.

پیش از تکیه بر این مهارت بدانید

• نسخهٔ اولیه: نسخهٔ فعلی 0.1.1 است و خود سازنده آن را نقطهٔ شروع می‌داند، نه فهرست زندهٔ وضعیت سرویس‌ها. بررسی خودکار میرورها و راهنمای جدا برای هر سیستم‌عامل در برنامهٔ نسخه‌های بعدی است و هنوز منتشر نشده است.
• میرورها آزموده نشده‌اند: هیچ‌کدام از ۲۲ میرور نامزد را سازنده نسنجیده است. نشانی میرورها، رفتار DNS و ابزارها با اپراتور و زمان عوض می‌شود.
• دادهٔ زنده ندارد: این مهارت سرور MCP نیست و به سرویسی وصل نمی‌شود. فرقش را در MCP چیست ببینید.
• قطعی کامل دور زده نمی‌شود: فقط کش و فایل‌هایی که از قبل دارید کمک می‌کنند.
• محدودیت منطقه‌ای سرویس‌ها: قاعدهٔ منطقه‌ای یک API هوش مصنوعی چیزی نیست که تونل «حلش» کند، و مهارت هم چنین وعده‌ای نمی‌دهد.
• اجازه برای هر تغییر: هر آزمون شبکه و هر تغییر در تنظیمات به تأیید شما نیاز دارد.
• سازنده: PsychoSofts، یک توسعه‌دهندهٔ مستقل، با مجوز MIT. بازارچه آن را نساخته است.

اگر بعد از این می‌خواهید دستیارتان به سرویس‌های ایرانی هم وصل شود و دادهٔ زنده بگیرد، از اتصال دستیار شروع کنید.

دفعهٔ بعد که نصب بسته‌ای گیر کرد، پیش از روشن کردن VPN، مهارت برنامه‌نویسی با اینترنت ایران را دریافت کنید و بگذارید دستیار اول علت را پیدا کند.