VS Code Remote SSH не подключается к удалённому Mac

Если VS Code Remote SSH не подключается к удалённому Mac, сначала выполните проверку через командную строку: если обычный SSH тоже не проходит, ищите проблему в сети, Remote Login или аутентификации; если SSH успешен, переходите к журналу Remote - SSH, установке VS Code Server, прокси и правам удалённого профиля. В течение этой недели не переустанавливайте расширение и не удаляйте каталог сервера вслепую — сначала сохраните журнал и зафиксируйте, на каком слое произошёл сбой.

Эта инструкция предназначена разработчикам, которые входят в macOS с Windows, Linux или другого Mac, а также DevOps- и платформенным инженерам, поддерживающим удалённые узлы для сборки и разработки. Она особенно полезна, если VS Code Server зависает при установке, окно остаётся на этапе подключения или расширения работают в локальном, а не удалённом окружении.

VS Code Remote SSH — это не только команда ssh. После установления SSH-сеанса редактор должен определить удалённую платформу, установить или запустить VS Code Server, связать его с локальным интерфейсом и затем открыть рабочую папку. Поэтому зелёный статус SSH ещё не означает, что вся цепочка готова.

Для каждого сбоя мы рекомендуем записывать четыре результата:

• команда ssh из терминала;
• сообщение в окне VS Code;
• последние строки канала вывода Remote - SSH;
• результат запуска терминала, открытия репозитория и проектной команды на удалённом Mac.

Такой журнал сразу отделяет сетевую проблему от ошибки редактора. Например, сообщение о тайм-ауте относится к достижимости узла, а зависание после слов о запуске сервера — уже к удалённому окружению или каналу между VS Code и VS Code Server.

Официальная документация VS Code рекомендует сначала проверить хост обычной командой ssh, а подробную информацию о следующем этапе смотреть в канале вывода Remote - SSH. (code.visualstudio.com)

Проверка имени и сетевого пути

Используйте тот же псевдоним, который выбран в VS Code:

ssh -v mac-dev

Если псевдонима нет, примените обычную форму:

ssh -v developer@example-host

Подставьте реальные значения только в локальном терминале. В публичную документацию, тикет или журнал нельзя копировать приватный ключ, пароль, токен и полный адрес производственного хоста.

Режим -v показывает, на каком этапе остановился OpenSSH. Ошибка разрешения имени указывает на DNS или неправильный HostName. Тайм-аут обычно требует проверки маршрута, сетевой политики, входного правила или доступности узла. Сообщение об отказе соединения означает, что адрес достигнут, но служба SSH не принимает соединение на указанной точке входа.

Не следует автоматически предполагать конкретный внешний порт или схему проброса. Если Mac расположен за корпоративным шлюзом, VPN или платформенным сетевым фильтром, проверяйте фактический маршрут и разрешённый способ доступа, предоставленный администратором.

Проверка настроек macOS

На удалённом Mac откройте:

Системные настройки → Основные → Общий доступ → Удалённый вход

Включите Remote Login и проверьте список пользователей, которым разрешён вход. Apple отдельно указывает, что Remote Login используется для доступа по SSH и SFTP; в настройке можно разрешить всех пользователей или выбрать конкретные учётные записи. (support.apple.com)

Если разработчику требуется доступ к файлам за пределами обычного домашнего каталога, проверяйте разрешения отдельно. Не включайте расширенный доступ без необходимости: для VS Code Remote SSH важнее корректная рабочая папка, права пользователя и отсутствие запрета на запуск нужных процессов.

Также проверьте встроенный сетевой экран macOS и внешние правила платформы. В руководстве Apple настройки Firewall находятся в разделе сетевой безопасности, где можно управлять разрешёнными входящими подключениями. (support.apple.com)

Важно: предупреждение о ключе хоста нельзя обходить удалением всех записей из known_hosts без анализа. Сначала сравните отпечаток с доверенным источником. Изменение отпечатка после пересоздания узла может быть ожидаемым, но в рабочей инфраструктуре также может указывать на подмену хоста.

Разделение трёх сетевых симптомов

Проверяйте симптомы в таком порядке:

1. Имя не разрешается — исправляйте HostName, DNS, VPN или локальный SSH Config.
2. Соединение долго не отвечает — проверяйте сетевой маршрут, доступность входа и правила фильтрации.
3. Соединение отклонено — проверяйте Remote Login, службу SSH и фактический порт.

Если команда ssh не завершает аутентификацию, VS Code пока не является главным подозреваемым. Переустановка Remote - SSH не исправит отключённый Remote Login или ошибочный адрес.

Повторение точно той же команды

VS Code должен использовать тот же пользователь, псевдоним и конфигурацию, которые успешно проверены в терминале. Если команда работает только в одной форме, например:

ssh -i ~/.ssh/mac-dev-key developer@example-host

добавьте параметры в SSH Config и проверьте уже псевдоним:

Host mac-dev
    HostName example-host
    User developer
    IdentityFile ~/.ssh/mac-dev-key

Затем выполните:

ssh mac-dev
ssh -G mac-dev

Команда ssh -G полезна тем, что показывает итоговую конфигурацию после применения блоков Host, пользовательских настроек и параметров по умолчанию. Если VS Code подключается к другому имени, использует другой конфигурационный файл или не видит IdentityFile, визуальный выбор хоста может выглядеть правильным, но фактически запускать другую конфигурацию.

В настройках VS Code можно указать отдельный SSH-конфиг через параметр remote.SSH.configFile. Официальная документация также описывает добавление хоста из команды Remote-SSH: Add New SSH Host.... (code.visualstudio.com)

Признаки ошибки ключа

Наиболее частые варианты:

• ключ не загружен в агент;
• указан не тот файл в IdentityFile;
• приватный ключ недоступен текущему пользователю;
• имя пользователя отличается от разрешённой учётной записи macOS;
• в конфиге сработал более общий блок Host *;
• после пересоздания узла сохранился старый отпечаток.

Проверяйте аутентификацию с подробным выводом:

ssh -vvv mac-dev

Ищите строки о выборе IdentityFile, предложенных методах аутентификации и результате проверки публичного ключа. На Windows дополнительно убедитесь, что VS Code использует ожидаемый OpenSSH-клиент, а не другой набор инструментов с отдельным агентом и конфигурацией.

Не вставляйте полный вывод -vvv в публичный отчёт без редактирования: имена пользователей, адреса, пути и фрагменты конфигурации могут раскрывать внутреннюю инфраструктуру.

Сначала определить место зависания

Откройте палитру команд и выберите канал вывода Remote - SSH. В зависимости от версии VS Code название пункта может отображаться в списке каналов вывода после первой попытки подключения.

Сохраните журнал до любых действий по очистке. Затем определите последнюю успешную операцию:

• определение платформы удалённого хоста;
• скачивание архива;
• передача архива на Mac;
• распаковка;
• запуск VS Code Server;
• установка канала связи;
• открытие рабочей папки.

VS Code Server устанавливается на удалённом хосте и обеспечивает связь между локальным экземпляром редактора и удалённой средой. Именно поэтому обычный SSH может работать, а VS Code Remote SSH — останавливаться на «подключении» или «инициализации». (code.visualstudio.com)

Скачивание и прокси

По официальной документации, при установке VS Code Server Remote - SSH обычно пытается скачать компоненты на удалённом хосте, а затем может перейти к локальной загрузке и передаче по SSH. Для установки требуется исходящий HTTPS-доступ к update.code.visualstudio.com и vscode.download.prss.microsoft.com; используется порт 443. (code.visualstudio.com)

Отсюда следуют две отдельные проверки:

• доступен ли интернет с самого Mac;
• доступен ли HTTPS с локального компьютера, если выбран локальный способ загрузки.

Локальный прокси автоматически не становится прокси удалённого Mac. Если удалённая сеть требует прокси, задайте его в удалённой среде согласно политике организации и проверьте переменные HTTP_PROXY и HTTPS_PROXY. Не переносите в статью или тикет реальные значения с логинами и паролями.

Диск, права и остаточные процессы

На удалённом Mac проверьте:

df -h
pwd
ls -ld "$HOME"
mkdir -p "$HOME/.vscode-server-test"
rm -rf "$HOME/.vscode-server-test"

Последние две команды выполняйте только в тестовом каталоге. Они показывают, может ли текущий пользователь создавать и удалять файлы в домашнем профиле.

Если журнал указывает на незавершённый процесс сервера, сначала используйте команду VS Code Remote-SSH: Kill VS Code Server on Host. Она предназначена для завершения удалённого сервера при проблемах Remote SSH. (code.visualstudio.com)

Удаление каталогов VS Code Server вручную — не первый шаг. Оно может привести к повторной загрузке компонентов и потере установленного удалённого состояния расширений. Перед очисткой сохраните журнал, убедитесь, что рабочий код находится в репозитории или резервной копии, и предупредите команду о возможном прерывании активной сессии.

Локальные и удалённые расширения

У VS Code есть два места выполнения расширений: локальная машина с интерфейсом и удалённый SSH-хост. Темы и часть UI-компонентов остаются локальными, а инструменты, работающие с кодом, терминалом, Git или отладчиком, обычно устанавливаются на удалённом Mac. В панели Extensions ищите отдельную группу удалённого хоста и проверяйте, где установлено нужное расширение. (code.visualstudio.com)

Это особенно важно для Apple Silicon. Расширение может подключаться успешно, но отдельный нативный модуль внутри него не поддерживать архитектуру удалённой системы. В таком случае причина находится не в SSH-канале, а в бинарной зависимости, рантайме или версии инструмента.

Проверка на удалённом терминале:

uname -m
which git
which node
which python3
echo "$PATH"

Команды должны выполняться внутри терминала VS Code после открытия удалённой папки, а не в локальном PowerShell, локальном Terminal или WSL.

Shell и PATH

Интерактивный терминал может загружать профиль оболочки, а процесс расширения — запускаться с другим набором переменных. Поэтому ситуация «терминал работает, а задача VS Code не видит node или git» не является противоречием.

Сравните:

echo "$SHELL"
echo "$PATH"
command -v git
git --version

Затем запустите ту же проектную команду через задачу или скрипт, который фактически не работает. Проверьте:

• рабочий каталог;
• права на репозиторий;
• переменные окружения;
• наличие нужного SDK;
• расположение бинарных файлов;
• архитектуру нативных зависимостей.

Не исправляйте проблему добавлением случайных экспортов в несколько shell-профилей. Сначала определите, какой процесс запускает задачу и какой профиль он действительно читает.

Критерий «подключение восстановлено»

Состояние нельзя считать исправленным только потому, что индикатор Remote SSH стал зелёным. Примите восстановление только после четырёх проверок:

• открыта правильная папка на удалённом Mac;
• новый терминал выполняет команду на удалённом узле;
• проектная команда запускается с ожидаемым PATH;
• отладка или тестовый сценарий завершается без ошибки удалённого расширения.

Если используется Git по SSH и ключ защищён парольной фразой, операции синхронизации из удалённого контекста могут зависать в отдельных сценариях. Документация VS Code предлагает для таких случаев рассмотреть HTTPS, командную строку или настройку мультиплексирования SSH-соединений. (code.visualstudio.com)

Используйте этот порядок, чтобы не возвращаться к уже проверенным слоям:

• Если ssh mac-dev не работает, выберите ветку сети, Remote Login или учётных данных; к VS Code Server переходите только после успешного входа.
• Если ssh mac-dev работает, но VS Code не начинает установку, проверьте выбранный SSH-конфиг, платформу хоста и журнал Remote - SSH.
• Если журнал останавливается на скачивании, выберите ветку HTTPS, прокси и способ загрузки; не удаляйте серверный каталог.
• Если архив передан, но сервер не запускается, проверьте свободное место, права домашнего каталога, остаточные процессы и совместимость среды.
• Если VS Code открывает окно, но проект не работает, выберите ветку удалённых расширений, PATH, Git, SDK и прав рабочей папки.
• Если проблема появляется только после перезагрузки Mac, сначала подтвердите повторную доступность SSH, затем проверьте автозапуск и состояние удалённого сервера.
• Если после очистки проблема возвращается, прекратите повторять очистку и сравните журнал с рабочим подключением; устойчивый повторяемый сбой обычно связан с окружением, политикой сети или конкретным расширением.

FAQ ниже не заменяет журнал: его задача — быстро выбрать правильный слой проверки, когда симптом уже известен.

Перезагрузка удалённого Mac может изменить не SSH-конфигурацию, а состояние самого узла: служба Remote Login ещё не поднялась, сеть получила другой маршрут, пользовательский профиль недоступен или старый процесс VS Code Server остался в некорректном состоянии.

Порядок восстановления:

1. Подождите, пока Mac снова появится в сети.
2. Выполните ssh mac-dev из того же локального окружения.
3. Если вход успешен, запустите подключение VS Code.
4. Откройте Remote - SSH output и сохраните новый журнал.
5. Сравните место остановки с журналом до перезагрузки.
6. При подтверждённом зависшем сервере используйте штатную команду завершения.
7. Откройте репозиторий и выполните реальную проверку проекта.

Для постоянно работающего узла важна не только возможность подключиться один раз, но и повторяемость после перезапуска. Если Mac используется как сборочный или разработческий узел, заранее документируйте владельца учётной записи, SSH-псевдоним, рабочий каталог, требуемые расширения и критерий восстановления.

Практическое правило: успешная повторная авторизация — это только половина проверки. Вторая половина — запуск проекта, Git-операции и отладки после перезапуска без ручного восстановления случайных переменных среды.

Переустановка расширения — не универсальная терапия. Если обычный SSH не проходит, она ничего не изменит. Если сервер не может скачать архив из-за прокси, переустановка лишь повторит ту же сетевую ошибку.

Для сравнения с локальной машиной можно использовать русскоязычную страницу JEXCLOUD, но перед переносом рабочего процесса сначала проверьте права, сетевой маршрут и доступность SSH по приведённой в статье схеме. Если требуется временный удалённый узел с полным SSH-доступом, варианты подключения можно сопоставить на странице аренды Mac. Выбор региона имеет смысл только после того, как подтверждены требования проекта к задержке, доступу и сетевой политике.

Перед тем как считать проблему закрытой, отметьте все пункты:

• [ ] Команда ssh использует тот же псевдоним, что и VS Code.
• [ ] Проверены User, HostName, IdentityFile и фактический SSH-конфиг.
• [ ] Remote Login включён, а нужная учётная запись допущена к входу.
• [ ] Сохранён журнал Remote - SSH до очистки или перезапуска.
• [ ] Определено, остановка происходит на сети, аутентификации, загрузке, распаковке или запуске сервера.
• [ ] Проверены свободное место и права домашнего каталога.
• [ ] Прокси проверен отдельно на локальной и удалённой стороне.
• [ ] Расширения установлены в правильном контексте — локальном или удалённом.
• [ ] В удалённом терминале проверены PATH, Git, SDK и архитектура.
• [ ] Открыта нужная рабочая папка.
• [ ] Выполнена проектная команда, а не только проверка статуса подключения.
• [ ] После перезапуска Mac подключение и рабочий процесс повторяются.

Если существующий узел регулярно исчезает после перезагрузки, не позволяет проверить Remote Login, не даёт административных прав или нестабилен для повторной диагностики, проблема уже выходит за рамки настройки VS Code. В таком случае аренда удалённого Mac у JEXCLOUD может оказаться практичнее самодельного узла: локальная машина ограничена режимом сна и доступностью конкретного инженера, Mac mini требует первоначальной покупки и самостоятельного обслуживания, а непостоянная тестовая среда усложняет повторную проверку. Для временной разработки, миграции или воспроизводимого тестового стенда разумно сначала сопоставить срок проекта, необходимость root-доступа и требования к физическим интерфейсам с доступными вариантами аренды Mac, а не покупать оборудование до подтверждения реальной нагрузки.

• Проверка SSH-туннеля, Health Check и LaunchAgent на удалённом Mac
• Настройка удалённого Mac по SSH и устранение сбоев launchd