mason.nvim: راهنمای نهایی برای مدیریت ابزار neovim شما

به راهنمای جامع برای mason.nvim، مدیر بسته قابل حمل طراحی شده برای ساده سازی گردش کار توسعه Neovim شما. اگر به دنبال نصب و مدیریت سرورهای LSP ، سرورهای DAP ، خطوط و فرمت ها هستید ، به جای مناسب رسیده اید. این آموزش شما را از طریق همه چیز از تنظیمات اساسی گرفته تا تنظیمات پیشرفته طی می کند ، و به شما کمک می کند تا قدرت کامل را مهار کنید mason.nvimبشر

آخرین نسخه: از نوشتن این راهنما ، آخرین نسخه v2.0.0 است. همیشه اطمینان حاصل کنید که برای بهترین ویژگی ها و رفع اشکال در آخرین نسخه هستید. برای به روزرسانی می توانید مخزن رسمی را بررسی کنید.

فهرست مطالب

1. مقدمه: mason.nvim چیست؟
2. تصاویر: نگاهی اجمالی به Mason.nvim
3. پیش نیازها: الزامات سیستم
4. نصب: شروع کار
5. تنظیم اولیه: پیکربندی mason.nvim
6. دستورات اصلی: ابزارهای روزانه شما
7. درک ثبت نام ها: منبع بسته ها
8. پنجره میسون: مدیریت بسته تعاملی
9. پیکربندی پیشرفته: خیاط Mason.nvim به نیازهای شما

10. با استفاده از بسته های نصب شده: ادغام با Neovim

11. پسوندها: گسترش قابلیت های Mason.nvim
12. استفاده برنامه ای: LUA API

13. عیب یابی و بهترین روشها

14. پایان

مقدمه: Mason.nvim چیست؟

mason.nvim یک افزونه قدرتمند Neovim است که برای ساده سازی مدیریت ابزار ویرایشگر خارجی طراحی شده است. آن را به عنوان یک مدیر بسته تخصصی که درست در داخل ویرایشگر خود زندگی می کند ، فکر کنید. این سرورهای LSP (پروتکل سرور زبان) ، سرورهای DAP (پروتکل آداپتور اشکال زدایی) ، خطوط و فرمت ها را از طریق یک رابط یکپارچه و بصری کنترل می کند.

چرا از mason.nvim استفاده می کنیم؟

توسعه مدرن غالباً نیاز به مجموعه ای از ابزارها برای زبان ها و وظایف مختلف دارد. نگه داشتن این ابزارها نصب ، به روز شده و به درستی پیکربندی می تواند یک سینک زمان قابل توجهی باشد. mason.nvim این مورد را توسط:

قابلیت حمل: این برنامه به طور مداوم در تمام سیستم عامل ها پشتیبانی Neovim (لینوکس ، MACOS ، ویندوز) اجرا می شود.
مدیریت متمرکز: یک رابط برای حاکم بر همه آنها. دیگر روشهای مختلف نصب برای هر ابزار را نمی توان به دست آورد.
سهولت استفاده: دستورات ساده و یک GUI اختیاری ، مدیریت بسته را به یک نسیم تبدیل می کند.
ادغام مسیر خودکار: ابزارهای نصب شده به طور خودکار در مسیر Neovim در دسترس هستند و به آنها امکان می دهد توسط ویژگی های داخلی Neovim (مانند :!با :terminal) و سایر افزونه ها.
کشف: به راحتی بسته های موجود و وضعیت آنها را مرور کنید.

مفاهیم اصلی

بسته ها: این ابزارهای فردی است که توسط آنها اداره می شود mason.nvim (به عنوان مثال ، lua-language-serverبا eslintبا codelldb).
ثبت ها: اینها منابعی هستند که لیستی از بسته های موجود و نحوه نصب آنها را ارائه می دهند. mason.nvim از یک رجیستری اولیه که توسط mason-org اما امکان ثبت نام های سفارشی را فراهم می کند.
فهرست نصب: بسته ها در فهرست داده های استاندارد Neovim نصب می شوند (:h standard-path، به طور معمول ~/.local/share/nvim/mason در Linux/MacOS). این باعث می شود سیستم شما تمیز و تاسیسات ابزار جدا شده به Neovim باشد.
دایرکتوری بن: اجرایی از بسته های نصب شده به یک واحد متصل می شوند mason/bin/ دایرکتوری ، که سپس به مسیر شما اضافه می شود.

2. تصاویر: نگاهی اجمالی از Mason.nvim

تصاویر اغلب بلندتر از کلمات صحبت می کنند. در README.md چندین تصویر را برجسته می کند mason.nvimرابط کاربری:

پنجره اصلی: نمای کلی از بسته های نصب شده ، در دسترس و در انتظار.
جزئیات بسته: اطلاعات مربوط به بسته های خاص ، از جمله وضعیت نصب و گزینه ها.
فیلتر زبان: به راحتی ابزارهای مربوط به زبانهای برنامه نویسی را که استفاده می کنید پیدا کنید.
طرح پیکربندی سرور LSP: (هرچند که اغلب توسط پسوندهای مانند اداره می شود mason-lspconfig.nvim) mason.nvim می تواند اطلاعات طرحواره را نمایش دهد.
اعلان ها را به روز کنید: در یک نگاه مشاهده کنید که کدام ابزار نسخه های جدیدی را در دسترس دارد.
پنجره راهنما: In-UI برای مراجعه سریع به صفحه کلید و ویژگی ها کمک می کند.

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

پیش نیازها: نیازهای سیستم

mason.nvim به گونه ای طراحی شده است که کاملاً سازگار باشد ، اما برخی از نیازهای پایه را دارد. این هوشمندانه چندین برنامه مشترک مشترک را امتحان می کند (به عنوان مثال ، wget یا curl) برای برآورده کردن وابستگی های آن ، تنظیمات را نرم تر می کند.

نسخه نئو

نئون >= 0.10.0: اطمینان حاصل کنید که نصب Neovim شما با این نسخه حداقل مطابقت دارد.

UNIX SYSTEMS (لینوکس ، MACOS)

git(1): برای واکشی ثبت نام ها و برخی از بسته ها.
curl(1) یا GNU wget(1): برای بارگیری مصنوعات بسته.
unzip(1): برای بیان بایگانی زیپ.
گون tar(1) (یا gtar(1) در بعضی از سیستم عامل ها مانند MACOS اگر پیش فرض است tar gnu tar نیست): برای فشرده سازی تاربال.
gzip(1): برای فشرده سازی پرونده های .gz.

بیشتر سیستم های مانند یونیکس این ابزارها را از قبل نصب شده یا به راحتی از طریق مدیر بسته سیستم خود در دسترس قرار می دهند (به عنوان مثال ، aptبا yumبا brew).

سیستم های ویندوز

PowerShell (pwsh) یا powershell: برای برنامه نویسی و اجرای.
git: برای واکشی ثبت نام ها و برخی از بسته ها.
گون tar: برای فشرده سازی تاربال. ممکن است لازم باشد این کار را به طور جداگانه نصب کنید (به عنوان مثال ، از طریق شکلات یا قاشق غذاخوری ، یا ممکن است با ویندوز همراه باشد).
یک ابزار بایگانی: یکی از موارد زیر برای رسیدگی به بایگانی مورد نیاز است:
[7-Zip][7zip][PeaZip][peazip][Archiver (mholt/archiver)][archiver][WinZip][winzip][WinRAR][winrar]

مدیران بسته خارجی

توجه به این نکته مهم است که mason.nvim خود یک مدیر برای دیگر ابزارها برخی از این ابزارها با استفاده از مدیران بسته بندی بومی خود نصب می شوند (به عنوان مثال ، cargo برای ابزارهای مبتنی بر زنگ زدگی ، npm برای ابزارهای مبتنی بر Node.js ، pip برای ابزارهای پایتون). بنابراین ، بسته به بسته های خاصی که قصد نصب آنها را دارید mason.nvim، همچنین ممکن است لازم باشد این مدیران بسته بندی زیرین را روی سیستم خود نصب کنید.

بررسی تنظیمات خود: :checkhealth mason

پس از نصب ، بهترین راه برای تأیید اینکه آیا سیستم شما تمام نیازها را برآورده می کند و لیست مفصلی را که ممکن است مدیران بسته خارجی خاص برای ابزاری که به آنها علاقه مند هستید نیاز باشد ، اجرای این است:

:checkhealth mason

این دستور گزارشی جامع در مورد ارائه می دهد mason.nvimوضعیت و هرگونه وابستگی از دست رفته.

4. نصب: شروع کار

mason.nvim می توان با استفاده از مدیر افزونه Neovim مورد علاقه خود نصب کرد. در اینجا دستورالعمل هایی برای برخی از محبوب ترین موارد وجود دارد:

با استفاده از packer.nvim

موارد زیر را به پیکربندی Packer خود اضافه کنید:

use {
    "mason-org/mason.nvim"
}

سپس ، اجرا کنید :PackerSync یا :PackerCompile پس از :PackerInstallبشر

با استفاده از lazy.nvim

موارد زیر را به پیکربندی Lazy.nvim خود اضافه کنید:

{
    "mason-org/mason.nvim",
    -- Optional: specify a version or other lazy.nvim options
    -- version = "v2.0.0",
    -- lazy = false, -- Eager load as recommended
}

سپس Neovim را مجدداً راه اندازی کنید یا دستور Lazy.NVIM مناسب را برای نصب افزونه های جدید اجرا کنید.

با استفاده از vim-plug

موارد زیر را به خود اضافه کنید vimrc یا init.vim در plug#begin() وت plug#end() بلوک:

Plug 'mason-org/mason.nvim'

سپس ، پرونده پیکربندی خود را (یا Neovim را مجدداً راه اندازی کنید) منبع دهید و اجرا کنید :PlugInstallبشر

5. تنظیم اولیه: پیکربندی mason.nvim

پس از نصب ، mason.nvim باید اولیه شود. این کار با تماس با آن انجام می شود setup() در پیکربندی LUA (به طور معمول init.lua).

راه اندازی اساسی

ساده ترین راه برای شروع کار:

require("mason").setup()

البته می توانید یک جدول پیکربندی را به setup() عملکردی برای سفارشی کردن رفتار آن. بعداً در این راهنما به گزینه های پیکربندی دقیق خواهیم پرداخت (به پیکربندی پیشرفته مراجعه کنید).

چه اتفاقی می افتد در طول راه اندازی؟

وقتی تماس می گیرید require("mason").setup()با mason.nvim چند عمل کلیدی را انجام می دهد:

1. پیشرفت مسیر: این جلسه Neovim را تغییر می دهد PATH متغیر محیط این تضمین می کند که اجرایی بسته های نصب شده توسط mason.nvim توسط Neovim و سایر افزونه ها قابل کشف هستند. به طور پیش فرض ، آن را آماده می کند bin دایرکتوری به PATHبشر
2. ثبت فرمان: این دستورات مختلف کاربر را ثبت می کند (مانند :Masonبا :MasonInstall، و غیره) که برای تعامل با افزونه استفاده خواهید کرد.

چرا بارگذاری مشتاق توصیه می شود

در README.md صریحاً بیان می کند: “mason.nvim بهینه سازی شده است تا در طول تنظیمات کمترین زمان را بارگیری کند. بارگذاری تنبل پلاگین ، یا به نوعی به تعویق انداختن تنظیم ، توصیه نمی شود. “

این توصیه های اساسی است. چون mason.nvim نیاز به اصلاح PATH در اوایل فرآیند راه اندازی Neovim برای سایر پلاگین ها و ویژگی های داخلی Neovim برای یافتن صحیح ابزارهایی که در آن قرار دارد ، بهتر است که اجازه دهید آن را با اشتیاق بارگذاری کرده و عملکرد تنظیم خود را اجرا کند (یعنی معوق یا تنبل یا تنبل). این تضمین می کند که تا زمانی که شما یا سایر افزونه ها به یک ابزار نیاز دارید ، mason.nvim قبلاً آن را در دسترس قرار داده است.

6. دستورات اصلی: ابزارهای روزانه شما

mason.nvim مجموعه ای از دستورات بصری را برای مدیریت بسته های خود فراهم می کند.

:Mason: مرکز مرکزی

دستور: :Mason
عمل: پنجره اصلی وضعیت گرافیکی را باز می کند. این رابط اصلی شما برای مرور بسته های موجود است ، با دیدن اینکه نصب شده است ، مدیریت تاسیسات (نصب ، حذف ، به روزرسانی) ، مشاهده جزئیات بسته و بررسی بسته های منسوخ. این یک روش بسیار تعاملی برای مدیریت ابزار شما است. مطبوعات g? در این پنجره برای دیدن KeyMaps موجود.

:MasonUpdate: تازه نگه داشتن ثبت نام ها

دستور: :MasonUpdate
عمل: به روزرسانی کلیه ثبت های بسته بندی شده. ثبت ها منبع حقیقت برای بسته های موجود و نسخه های آنها هستند. اجرای این دستور تضمین می کند mason.nvim از آخرین نسخه های بسته و هر بسته جدیدی که به ثبت ها اضافه شده است ، می داند. اجرای این کار به صورت دوره ای خوب است.

:MasonInstall ...: اضافه کردن ابزارهای جدید

دستور: :MasonInstall [package_name_2 ...]
مثال: :MasonInstall lua-language-server stylua
عمل: بسته های مشخص شده را نصب یا نصب مجدد می کند. می توانید چندین بسته جدا شده توسط فضاها را لیست کنید.
پین کردن نسخه: می توانید نسخه خاصی از یک بسته را با ضمیمه نصب کنید @ به نام بسته به عنوان مثال:

```vim
:MasonInstall rust-analyzer@nightly
:MasonInstall yamllint@1.26.3
```

You'll need to refer to the specific package's release pages or the registry information to find available version tags.

حالت بدون سر: mason.nvim از نصب بسته ها در حالت بدون سر پشتیبانی می کند ، که برای برنامه نویسی یا تنظیمات خودکار مفید است:

```sh
nvim --headless -c "MasonInstall lua-language-server rust-analyzer" -c qall
```

In headless mode, the command runs in a blocking fashion, meaning Neovim will wait until the installations are complete before proceeding with further commands or exiting.

:MasonUninstall ...: حذف ابزار

دستور: :MasonUninstall [package_name_2 ...]
مثال: :MasonUninstall stylua
عمل: بسته های مشخص شده را از سیستم خود حذف کنید (به طور خاص ، از mason.nvim فهرست نصب).

:MasonUninstallAll: یک تخته سنگ تمیز

دستور: :MasonUninstallAll
عمل: حذف نصب همه بسته هایی که در حال حاضر توسط mason.nvimبشر با احتیاط استفاده کنید ، زیرا این همه ابزارهایی را که از طریق آنها نصب کرده اید حذف می کند mason.nvimبشر

:MasonLog: عیب یابی و تشخیص

دستور: :MasonLog
عمل: باز می شود mason.nvim پرونده را در یک پنجره برگه جدید وارد کنید. این برای اشکال زدایی مسائل مربوط به نصب یا درک چه چیزی بسیار ارزشمند است mason.nvim در پشت صحنه انجام می شود. اگر با مشکل روبرو شوید ، پرونده ورود به سیستم اغلب اولین جایی است که به دنبال سرنخ ها است.

7. درک ثبت ها: منبع بسته ها

ثبت ها برای چگونگی اساسی است mason.nvim بسته ها را کشف و مدیریت می کند. آنها در اصل لیست تعاریف بسته هستند ، mason.nvim چه ابزارهایی در دسترس است ، آنها را از کجا بارگیری کنید و نحوه نصب آنها.

رجیستری پیش فرض

به طور پیش فرض ، mason.nvim از رجیستری بسته اصلی واقع در Mason-org/Mason-Registry استفاده می کند. این رجیستری توسط mason.nvim توسعه دهندگان و مشارکت کنندگان و حاوی طیف گسترده ای از ابزارهای توسعه مشترک است. می توانید لیست تمام بسته های رسمی پشتیبانی شده را در https://mason-registry.dev/registry/list مرور کنید.

ثبت های سفارشی

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

می توانید ثبت های سفارشی را در setup() تماس:

require("mason").setup({
    registries = {
        "lua:my-custom-lua-registry", -- A custom registry defined in Lua
        "github:my-org/my-mason-registry", -- A custom GitHub-hosted registry
        "github:mason-org/mason-registry" -- The default registry
    }
})

قالب رشته های رجیستری می تواند باشد lua:your_module_name برای ثبت های مبتنی بر LUA یا github:username/repo-name برای موارد میزبان GitHub.

تقدم رجیستری

اگر بسته ای با همین نام در چندین ثبت شده پیکربندی شده وجود داشته باشد ، mason.nvim از تعریف از رجیستری که ظاهر می شود استفاده خواهد کرد اولی در شما registries لیست در مثال بالا ، اگر my-custom-lua-registry بسته ای به نام داشت my-tool وت mason-org/mason-registry همچنین یکی ، تعریف از my-custom-lua-registry استفاده می شود

به روز نگه داشتن ثبت نام ها

قبل از نصب یا به روزرسانی هر بسته ، mason.nvim نیاز به بارگیری یا تازه کردن نسخه محلی ثبت شده های پیکربندی شده دارد. این اتفاق به طور خودکار هنگام استفاده از دستوراتی مانند اتفاق می افتد :MasonInstall یا :Mason (در صورت پیکربندی برای بررسی به روزرسانی ها). همچنین می توانید این کار را به صورت دستی انجام دهید :MasonUpdateبشر

اگر در تعامل هستید mason.nvim بسته ها از طریق API LUA خود ، از طریق برنامه نویسی ، استفاده از آن را توصیه می کند mason-registry.refresh() و/یا mason-registry.update() توابع برای اطمینان از داشتن آخرین اطلاعات بسته.

8. پنجره میسون: مدیریت بسته تعاملی

در :Mason Command یک پنجره تعاملی را باز می کند که به عنوان کنترل پنل شما برای مدیریت بسته عمل می کند. در اینجا کمی بیشتر در مورد آنچه می توانید انجام دهید وجود دارد:

بسته ها را کاوش کنید: لیستی از تمام بسته های موجود از ثبت های پیکربندی شده خود را مشاهده کنید.
مشاهده وضعیت: نمادها و متن نشان می دهد که آیا یک بسته نصب شده است ، نصب نشده ، در انتظار نصب یا به روزرسانی در دسترس است.
نصب/حذف/به روزرسانی: بسته ها را انتخاب کرده و مستقیماً از طریق رابط کاربری روی آنها انجام دهید.
مشاهده جزئیات بسته: برای دیدن اطلاعات بیشتر ، یک ورودی بسته را گسترش دهید ، توضیحات ، نسخه و گاهی اوقات به صفحه اصلی یا منبع آن پیوند دهید.
فیلتر بر اساس زبان: اگر به دنبال ابزارهای پایتون هستید ، می توانید لیست را فیلتر کنید تا فقط بسته های مربوط به پایتون را نشان دهید.
بسته های منسوخ شده را بررسی کنید: به سرعت ابزارهای نصب شده ای را که نسخه های جدیدتری دارند ، شناسایی کنید.

پیمایش UI

ناوبری به طور معمول با کلیدهای استاندارد حرکت neovim انجام می شود (jبا k، و غیره). UI به گونه ای طراحی شده است که شهودی باشد.

KeyBinds برای کارآیی

وقتی پنجره میسون باز شد ، فشار دهید g? برای جابجایی یک راهنمای راهنما که لیست همه KyMaps موجود را نشان می دهد. اقدامات متداول مانند نصب ، حذف ، به روزرسانی و جزئیات بسته بندی بسته بندی ، به کلیدهای مناسب محدود می شود. در README.md و پیکربندی پیش فرض این موارد را ببینید (نگاه کنید به ui.keymaps در بخش پیکربندی پیش فرض README). آشنایی با این صفحه کلید به طور قابل توجهی وظایف مدیریت بسته شما را سرعت می بخشد. برخی از پیش فرض ها عبارتند از:

: گسترش بسته بندی/جزئیات بسته بندی (یا در صورت گسترش ، ورود به سیستم نصب بسته بندی را انجام دهید).
i: بسته را در زیر مکان نما نصب کنید.
u: بسته بندی را در زیر مکان نما به روز کنید.
X: بسته را زیر مکان نما حذف کنید.
U: تمام بسته های نصب شده را به روز کنید.
C: بررسی کنید که بسته های نصب شده منسوخ شده اند.
c: نسخه جدیدی از بسته را در زیر مکان نما بررسی کنید.
: فیلتر زبان را اعمال کنید.
g?: نمای راهنما را تغییر دهید.

سفارشی کردن این kymaps از طریق ui.keymaps تنظیم پیکربندی.

9. پیکربندی پیشرفته: خیاط Mason.nvim به نیازهای شما

در حالی که تنظیمات پیش فرض برای mason.nvim برای اکثر کاربران معقول هستند ، می توانید رفتار آن را به طور گسترده از طریق setup() عملکرد. در README.md لیست کاملی از تنظیمات پیش فرض را ارائه می دهد ، که همچنین به عنوان مرجع برای کلیه گزینه های پیکربندی موجود عمل می کند.

دسترسی به گزینه های پیکربندی

شما یک میز lua را به
در setup() عملکرد در طول اولیه سازی. به عنوان مثال:

require("mason").setup({
    -- Target directory for installations
    install_root_dir = "/path/to/my/custom/mason_packages",

    -- Log level
    log_level = vim.log.levels.DEBUG, -- Useful for troubleshooting

    -- UI customizations
    ui = {
        border = "rounded", -- Use rounded borders for the Mason window
        icons = {
            package_installed = "✅",
            package_pending = "⏳",
            package_uninstalled = "❌"
        }
    },

    -- Custom list of registries (ensure default is included if still needed)
    registries = {
        "github:my-org/internal-tools-registry",
        "github:mason-org/mason-registry"
    },

    -- Pip configuration
    pip = {
        upgrade_pip = true,
        install_args = {"--no-cache-dir"}
    }
})

گزینه های کلیدی پیکربندی توضیح داده شده است

بیایید برخی از مهمترین گزینه های پیکربندی موجود را تجزیه کنیم. لیست کامل را می توان در README.md یا با مشاوره :help mason-default-settingsبشر

install_root_dir (string)
پیش فرض: path.concat { vim.fn.stdpath "data", "mason" } (به عنوان مثال ، ~/.local/share/nvim/mason در لینوکس)
هدف: فهرست را در کجا مشخص می کند mason.nvim تمام بسته ها را نصب می کند. اگر یک ترجیح ساختار دایرکتوری خاص دارید یا نیاز به مدیریت بسته ها در یک درایو قابل حمل دارید ، ممکن است این مسئله را تغییر دهید.

PATH ("prepend" | "append" | "skip")
پیش فرض: "prepend"
هدف: چگونه کنترل می کند mason.nvim Neovim’s را اصلاح می کند PATH متغیر محیط
"prepend": اضافه می کند mason.nvim‘s bin دایرکتوری به شروع از PATHبشر این بدان معنی است که اجرایی که توسط mason.nvim اگر نامگذاری درگیری با ابزارهای نصب شده سیستم وجود داشته باشد ، برتری خواهد داشت. این به طور کلی توصیه می شود.
"append": اضافه می کند mason.nvim‘s bin دایرکتوری به پایان از PATHبشر ابزارهای نصب شده در سیستم در صورت درگیری مقدم هستند.
"skip": mason.nvim اصلاح نمی کند PATHبشر شما مسئول اطمینان از آن هستید bin دایرکتوری در شماست PATH اگر می خواهید ابزار در دسترس باشد.

log_level (vim.log.levels.TRACE | DEBUG | INFO | WARN | ERROR)
پیش فرض: vim.log.levels.INFO
هدف: کمبود ورود به سیستم را کنترل می کند mason.nvim پرونده ورود به سیستم (قابل مشاهده با :MasonLog). برای استفاده عادی ، INFO خوب است هنگام اشکال زدایی در مورد نصب بسته بندی ، این را تنظیم کنید vim.log.levels.DEBUG می تواند اطلاعات تشخیصی بسیار دقیق تری را ارائه دهد.

max_concurrent_installers (number)
پیش فرض: 4
هدف: حداکثر تعداد بسته هایی را که می توان همزمان نصب کرد محدود می کند. اگر درخواست کنید بسته های بیشتری را از این حد نصب کنید ، بسته های اضافی با تکمیل نصب های قبلی در صف قرار می گیرند و نصب می شوند. این مانع از غلبه بر سیستم یا اتصال شبکه شما می شود.

registries (table از string)
پیش فرض: {"github:mason-org/mason-registry"}
هدف: لیستی از منابع رجیستری. همانطور که در بخش ثبت ها بحث شد ، این به شما امکان می دهد منابع بسته بندی پیش فرض و سفارشی را مشخص کنید. سفارش برای تقدم.

providers (table از string)
پیش فرض: {"mason.providers.registry-api", "mason.providers.client"}
هدف: چگونه تعریف می کند mason.nvim مانند نسخه های موجود ، ابرداده بسته بندی تکمیلی را حل می کند. در صورت عدم موفقیت موارد قبلی ، چندین ورودی را می پذیرد و از ورودی های بعدی به عنوان برگشتی استفاده می کند.
mason.providers.registry-api: استفاده می کند https://api.mason-registry.dev API این به طور کلی سریع است و اطلاعات جامع را ارائه می دهد.
mason.providers.client: فقط از ابزار سمت مشتری استفاده می کند (به عنوان مثال ، git دستورات علیه یک کلون رجیستری محلی) برای حل ابرداده. اگر API در دسترس نباشد یا اگر ترجیح می دهید به یک API خارجی اعتماد نکنید ، می تواند یک بازپرداخت باشد.

github.download_url_template (string)
پیش فرض: "https://github.com/%s/releases/download/%s/%s"
هدف: یک تنظیم پیشرفته که الگوی URL را برای بارگیری دارایی ها از نسخه های GitHub تعریف می کند. متقاضیان برای: 1. مخزن (به عنوان مثال ، owner/repo) ، نسخه انتشار (به عنوان مثال ، v1.0.0) ، 3. نام دارایی. اگر از یک نمونه شرکت GitHub با ساختار URL متفاوت یا یک پروکسی برای بارگیری های GitHub استفاده می کنید ، معمولاً این مسئله را تغییر می دهید.

pip (table)
upgrade_pip (boolean):
پیش فرض: false
هدف: اگر trueبا mason.nvim سعی در به روزرسانی خواهد داشت pip به آخرین نسخه خود در محیط مجازی Python ، آن را برای یک بسته پایتون ایجاد می کند پیش از نصب خود بسته. این می تواند به اطمینان از سازگاری و دسترسی به جدیدترین کمک کند pip ویژگی ها
install_args (table از string):
پیش فرض: {} (جدول خالی)
هدف: به شما امکان می دهد آرگومان های اضافی را که به آن منتقل می شود مشخص کنید pip install دستورات به عنوان مثال ، شما ممکن است از این برای تنظیم پروکسی استفاده کنید: install_args = {"--proxy", "https://your.proxy.server:port"}بشر این مستندات هشدار می دهد که تنظیم استدلال های اضافی ممکن است بر رفتار مورد نظر تأثیر بگذارد و به طور کلی توصیه نمی شود مگر اینکه بدانید چه کاری انجام می دهید.

ui (table) – این جدول تو در تو اجازه می دهد تا سفارشی سازی گسترده ای از :Mason پنجره
check_outdated_packages_on_open (boolean):
پیش فرض: true
هدف: اگر trueبا mason.nvim هر بار که باز می کنید به طور خودکار نسخه های جدید بسته های نصب شده خود را بررسی می کنید :Mason پنجره بریدن false اگر ترجیح می دهید به صورت دستی بررسی کنید ، این مسئله را غیرفعال کنید (به عنوان مثال ، C KEYMAP).
border (string یا table):
پیش فرض: nil (این به معنای پیش فرض برای Neovim است 'winborder' تنظیم)
هدف: سبک مرزی را برای پنجره UI تعریف می کند. مقادیر مرزی مشابه را می پذیرد nvim_open_win()بشر شما می توانید از سبک های از پیش تعریف شده مانند استفاده کنید "none"با "single"با "double"با "rounded"با "solid"با "shadow"، یا شخصیت های مرزی سفارشی را تعریف کنید.
backdrop (number):
پیش فرض: 60
هدف: کدورت پس زمینه را برای پنجره میسون تنظیم می کند ، جایی که 0 کاملاً مات است و 100 کاملاً شفاف است این امر در کمبود محتوای ویرایشگر زیربنایی هنگام باز شدن پنجره میسون تأثیر می گذارد. (موجود از V1.11.0)
width (number یا float):
پیش فرض: 0.8 (80 ٪ از عرض صفحه)
هدف: عرض پنجره میسون را کنترل می کند. یک عدد صحیح بیشتر از 1 یک عرض ثابت را در ستون ها قرار می دهد. شناور بین 0 تا 1 درصد از عرض صفحه نمایش را تعیین می کند.
height (number یا float):
پیش فرض: 0.9 (90 ٪ از ارتفاع صفحه)
هدف: ارتفاع پنجره میسون را کنترل می کند. یک عدد صحیح بیشتر از 1 ارتفاع ثابت را در ردیف ها قرار می دهد. شناور بین 0 تا 1 درصد از ارتفاع صفحه نمایش را تعیین می کند.
icons (table):
پیش فرض: { package_installed = "◍", package_pending = "◍", package_uninstalled = "◍" }
هدف: به شما امکان می دهد نمادها (کاراکترهای) مورد استفاده در پنجره میسون را برای نشان دادن وضعیت بسته بندی کنید. این امر برای شخصی سازی ظاهر و احساس بسیار عالی است ، به خصوص اگر از یک فونت nerd استفاده کنید یا ترجیحات زیبایی شناسی خاصی داشته باشید.
package_installed: نماد برای یک بسته نصب شده.
package_pending: نماد بسته ای که هم اکنون برای نصب نصب یا صف بندی شده است.
package_uninstalled: نماد بسته ای که نصب نشده است.
در README.md مثال استفاده می کند: ✓با ➜با ✗بشر
keymaps (table):
هدف: به شما امکان می دهد کلید های کلید استفاده شده در پنجره میسون را سفارشی کنید. پیش فرض ها در README.md و به طور کلی کاملاً معقول هستند. اگر آنها با کلید های شخصی شما مغایرت دارند یا اگر طرح دیگری را ترجیح می دهید ، می توانید هر یک از این اقدامات را به کلیدهای مختلف بازسازی کنید. (به README.mdپیکربندی پیش فرض برای لیست کامل اقدامات قابل تنظیم مانند toggle_package_expandبا install_packageبا update_all_packages، و غیره)

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

10. با استفاده از بسته های نصب شده: ادغام با Neovim

هنگامی که یک بسته (مانند سرور LSP یا یک قالب ساز) از طریق نصب می شود mason.nvim، چگونه واقعاً از آن استفاده می کنید؟

ادغام مسیر خودکار

همانطور که قبلاً ذکر شد ، mason.nvim به طور خودکار دایرکتوری حاوی اجرایی بسته های نصب شده خود را اضافه می کند (ITS mason/bin/ دایرکتوری) به Neovim PATHبشر این یک راحتی قابل توجه است زیرا به این معنی است:

Neovim Buildins: شما می توانید با استفاده از روشهای داخلی Neovim برای اجرای دستورات خارجی ، مستقیماً از این ابزارها استفاده کنید:
:! (به عنوان مثال ، :! stylua --check .)
:terminal (به عنوان مثال ، :terminal eslint_d .)
jobstart() / vim.loop.spawn() برای اجرای پیشرفته تر ناهمزمان در اسکریپت های LUA.
افزونه های دیگر: بسیاری از افزونه های Neovim دیگر که انتظار دارند ابزارها در دسترس باشند PATH به طور خودکار نسخه های مدیریت شده توسط mason.nvim بدون هیچ پیکربندی اضافی

استفاده از افزونه های شخص ثالث

در حالی که دعوت مستقیم امکان پذیر است ، یکپارچه ترین و قدرتمندترین روش برای استفاده از ابزارهای نصب شده توسط mason.nvim اغلب از طریق سایر افزونه های تخصصی neovim است. به عنوان مثال:

سرورهای LSP: شما به طور معمول از یک افزونه مانند استفاده خواهید کرد nvim-lspconfig برای پیکربندی و اتصال سرورهای LSP به بافرهای خود.
Formatters/Linters: افزونه هایی مانند null-ls.nvim (گرچه اکنون بایگانی شده است ، بسیاری هنوز هم از آن استفاده می کنند یا چنگال/جانشینان آن مانند none-ls.nvim) یا افزونه های اختصاصی فرمتر را می توان برای استفاده از اجرایی ارائه شده توسط mason.nvimبشر
سرورهای DAP: افزونه آداپتور اشکال زدایی مانند nvim-dap برای رابط با سرورهای DAP نصب شده توسط mason.nvimبشر

mason.nvim تمرکز بر روی نصب و مدیریت از این ابزارها در ادغام و استفاده از این ابزارها در گردش کار ویرایش شما به طور معمول توسط این افزونه های تخصصی دیگر اداره می شوند.

مثال: mason-lspconfig.nvim

یک افزونه همراه بسیار رایج و بسیار توصیه شده است mason-lspconfig.nvimبشر این پسوند به عنوان پلی بین عمل می کند mason.nvim وت nvim-lspconfigبشر

این تضمین می کند که سرورهای LSP از طریق mason.nvim به طور خودکار با پیکربندی شده nvim-lspconfigبشر
این می تواند باعث شود که هنگام باز کردن نوع پرونده ای که یک سرور حذف نشده برای آن توصیه می شود ، سرورهای LSP مفقود شده را نصب کنید.

برای استفاده از آن ، به طور معمول هر دو را نصب می کنید mason.nvim وت mason-lspconfig.nvim، و سپس در شما nvim-lspconfig تنظیم ، شما به آن می گویید که استفاده کند mason-lspconfig برای مدیریت تعاریف سرور:

-- Example: After setting up nvim-lspconfig
require("mason").setup()
require("mason-lspconfig").setup({
    -- A list of servers to ensure are installed.
    -- These will be installed automatically by mason-lspconfig.
    -- Alternatively, you can leave this empty and install manually
    -- or use the ensure_installed function.
    ensure_installed = { "lua_ls", "cssls", "html", "jsonls", "tsserver" },
    -- You can also pass settings to mason.nvim's setup function here
    -- if you want to customize mason from mason-lspconfig
})

-- In your nvim-lspconfig setup, you would then iterate over servers
-- that mason-lspconfig knows about:
local lspconfig = require('lspconfig')
local capabilities = require('cmp_nvim_lsp').default_capabilities() -- if using nvim-cmp

require('mason-lspconfig').setup_handlers {
    -- The first entry (without a key) will be the default handler.
    -- This will be called for all servers that are not handled by a specific handler.
    function (server_name)
        lspconfig[server_name].setup {
            capabilities = capabilities
            -- Add other common server configurations here
        }
    end,
    -- Specific handlers for certain servers
    ["lua_ls"] = function ()
        lspconfig.lua_ls.setup {
            capabilities = capabilities,
            settings = {
                Lua = {
                    diagnostics = {
                        globals = {'vim'},
                    },
                },
            },
        }
    end,
    -- ... other custom server setups
}

این هم افزایی بین mason.nvim (برای نصب) و mason-lspconfig.nvim با nvim-lspconfig (برای پیکربندی و پیوست) تنظیم LSP بسیار قوی و آسان برای مدیریت را فراهم می کند.

11. پسوندها: گسترش قابلیت های Mason.nvim

اکوسیستم Neovim بر روی افزونه هایی که با هم کار می کنند شکوفا می شود. mason.nvim از این قاعده مستثنی نیست و دارای لیست رو به رشد از پسوندهای شخص ثالث است که عملکرد آن را تقویت می کند یا آن را با سایر قسمت های تنظیم Neovim شما ادغام می کند.

مقام رسمی README.md به صفحه ویکی برای پسوندها به عنوان منبع اصلی کشف این موارد اشاره می کند.

همانطور که در بالا برجسته شد ، mason-lspconfig.nvim یک نمونه اصلی است. ممکن است پسوندهای دیگری برای:

ادغام آسان تر با افزونه های DAP خاص.
پیشرفت های UI یا رابط های جایگزین برای mason.nvimبشر
روالهای تنظیم خودکار برای برنامه های ابزار مشترک.

کاوش در این صفحه ویکی می تواند موارد اضافی ارزشمند شما را کشف کند mason.nvimگردش کار قدرتمند.

12. استفاده برنامه ای: Lua API

در حالی که دستورات (:MasonInstall، و غیره) و UI (:Mason) برای بسیاری از کاربران کافی است ، mason.nvim همچنین یک API LUA را برای کنترل پیشرفته تر برنامه نویسی در معرض دید قرار می دهد. این به ویژه برای:

توسعه دهندگان افزونه که می خواهند ادغام شوند mason.nvimعملکرد در افزونه های خود (به عنوان مثال ، برای اطمینان از نصب یک ابزار وابستگی).
کاربرانی که می خواهند در پیکربندی neovim خود ، تنظیمات پیچیده یا منطق مدیریت بسته را اسکریپت کنند.

در README.md این مورد را ذکر می کند و به ویژگی های بیشتری که از طریق API در دسترس است نسبت به دستورات به تنهایی اشاره می کند. به طور خاص ، برای ثبت ها ، پیشنهاد می کند:

اگر از API های Lua میسون برای دسترسی به بسته ها استفاده می کنید ، توصیه می شود از آن استفاده کنید [:h mason-registry.refresh()][help-mason-registry-refresh] و/یا [:h mason-registry.update()][help-mason-registry-update] توابع برای اطمینان از داشتن آخرین اطلاعات بسته قبل از بازیابی بسته ها.

در doc/mason.txt پرونده (به طور خاص بخش های مشخص شده با *mason-api-...* برچسب ها ، اگر دسترسی کامل داشته باشم) منبع قطعی برای مستندات دقیق API خواهد بود. اگر قصد استفاده از API LUA را دارید ، باید مشورت کنید :help mason.nvim و به دنبال بخش های خاص API باشید. مناطق کلیدی API احتمالاً شامل توابع:

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

به عنوان مثال ، شما ممکن است یک API مانند require("mason-registry").get_package("lua-language-server") برای دریافت جزئیات بسته ، یا require("mason.installer").install("stylua") برای شروع نصب. عملکردهای دقیق و استفاده از آنها در پرونده های راهنما به تفصیل ارائه می شود.

13. عیب یابی و بهترین روشها

حتی با یک ابزار کاربر پسند مانند mason.nvim، ممکن است گهگاه به مواردی بپردازید یا می خواهید اطمینان حاصل کنید که از آن بهینه استفاده می کنید.

بررسی سلامتی با :checkhealth mason

همانطور که در بخش مورد نیاز ذکر شد ، :checkhealth mason اولین درگاه تماس شما برای تشخیص است. این خواهد بود:
تأیید کنید که Neovim با الزامات نسخه مطابقت دارد.
وجود وابستگی های اساسی خارجی را بررسی کنید (gitبا curlبا tar، و غیره) برای سیستم عامل شما.
به طور بالقوه وابستگی های اختیاری را بر اساس بسته های موجود لیست کنید (به عنوان مثال ، cargo اگر ابزارهای مبتنی بر زنگ زدگی در رجیستری هستند).
گزارش هرگونه مشکلات پیکربندی مشترک.

اجرای این کار بعد از نصب و هر زمان که مشکوک هستید ، می تواند زمان زیادی را صرفه جویی کند.

مشاوره با سیاههها :MasonLog

اگر یک بسته نتواند نصب کند ، یا چیزی غیر منتظره رفتار کند ، :MasonLog فرمان ارزشمند است. این باز می شود mason.nvimپرونده ورود به سیستم سطح جزئیات موجود در این سیاهه توسط log_level تنظیم در پیکربندی خود. برای عیب یابی ، آن را تنظیم کنید vim.log.levels.DEBUG برای کسب بیشترین اطلاعات:

require("mason").setup({
    log_level = vim.log.levels.DEBUG
})

سپس دوباره عملیات ناکام را امتحان کنید و سیاهه را بررسی کنید. این معمولاً حاوی پیام های خطا از فرآیند نصب اساسی ، مشکلات شبکه یا مشکلات مجوز است.

مشکلات گزارشگری

اگر فکر می کنید اشکالی پیدا کرده اید mason.nvim خود یا درخواست ویژگی ، بهترین مکان برای گزارش آن ، صفحه مسائل مربوط به GitHub برای پروژه است. هنگام گزارش یک مسئله:
اطمینان حاصل کنید که در آخرین نسخه از mason.nvimبشر
بررسی کنید که آیا این مسئله قبلاً گزارش شده است یا خیر.
اقدامات روشنی برای تولید مثل مشکل ارائه دهید.
شامل خروجی :checkhealth masonبشر
قطعه های مربوطه را از خود درج کنید :MasonLog (مخصوصاً با log_level بریدن DEBUG).
سیستم عامل و نسخه neovim خود را ذکر کنید.

بهترین روشها

نگه داشتن mason.nvim به روز شده: مانند هر افزونه ، به روز کنید mason.nvim خود به طور مرتب از طریق مدیر افزونه خود برای به دست آوردن آخرین ویژگی ها ، رفع اشکال و بهبود عملکرد.
دویدن :MasonUpdate به صورت دوره ای: حافظه پنهان محلی خود را با دویدن تازه نگه دارید :MasonUpdate برای اطمینان از دسترسی به آخرین نسخه های بسته.
پسوند اهرم: چرخ را دوباره اختراع نکنید. از برنامه های افزودنی مانند استفاده کنید mason-lspconfig.nvim برای کارهای ادغام مشترک.
اسناد را بخوانید: وقتی شک دارید ، کمک داخلی (:help mason.nvim) دوست شما است. در README.md همچنین یک منبع عالی است.
شروع ساده: با پیکربندی پیش فرض شروع کنید و فقط آنچه را که لازم دارید سفارشی کنید.

14. نتیجه گیری

mason.nvim به عنوان ابزاری اساسی برای هر کاربر جدی Neovim معرفی می شود. با انتزاع پیچیدگی های نصب و مدیریت مجموعه متنوعی از ابزارهای توسعه خارجی ، به شما امکان می دهد تا روی آنچه واقعاً مهم است تمرکز کنید: کد نوشتن. رابط بصری آن ، مجموعه ویژگی های قوی و پشتیبانی قوی جامعه باعث خوشحالی آن می شود.

از فرآیند نصب و راه اندازی ساده خود گرفته تا مدیریت بسته قدرتمند خط فرمان و مدیریت بسته بندی UI و قابلیت توسعه آن از طریق تنظیمات سفارشی و افزونه های شخص ثالث ، mason.nvim یک راه حل جامع برای استفاده از ابزار neovim شما ارائه می دهد.