Solana 문서시작하기

설치

이 섹션에서는 Solana 개발을 위한 로컬 환경 설정 단계를 다룹니다.

빠른 설치

Mac 및 Linux에서는 다음 명령어 하나로 모든 종속성을 설치할 수 있습니다.

Terminal
$
curl --proto '=https' --tlsv1.2 -sSfL https://solana-install.solana.workers.dev | bash

Windows 사용자: 먼저 WSL을 설치해야 합니다(종속성 설치 참조). 그런 다음 Ubuntu(Linux) 터미널에서 위 명령어를 실행하세요.

설치 후에는 다음과 같은 출력이 표시되어야 합니다:

Installed Versions:
Rust: rustc 1.86.0 (05f9846f8 2025-03-31)
Solana CLI: solana-cli 2.2.12 (src:0315eb6a; feat:1522022101, client:Agave)
Anchor CLI: anchor-cli 0.31.1
Node.js: v23.11.0
Yarn: 1.22.1

빠른 설치 명령어가 작동하지 않는 경우, 아래의 종속성 설치 섹션을 참조하여 각 종속성을 개별적으로 설치하는 방법을 확인하세요.

빠른 설치 명령어가 성공적으로 실행되면, 아래의 Solana CLI 기본 사항Anchor CLI 기본 사항 섹션으로 건너뛰세요.

종속성 설치

아래 지침은 각 종속성을 개별적으로 설치하는 과정을 안내합니다.

  • Windows 사용자는 먼저 WSL(Windows 서브시스템 for Linux)을 설치한 다음 아래 Linux 섹션에 명시된 종속성을 설치해야 합니다.
  • Linux 사용자는 먼저 아래 Linux 섹션에 명시된 종속성을 설치해야 합니다.
  • Mac 사용자는 아래 Rust 설치 지침부터 시작해야 합니다.

Rust 설치하기

개발자들은 Rust 프로그래밍 언어를 사용하여 Solana 프로그램을 구축합니다.

rustup을 사용하여 Rust를 설치하세요.

다음 명령을 실행하여 Rust를 설치하세요:

Terminal
$
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

설치가 완료되면 다음과 같은 메시지가 표시됩니다:

다음 명령을 실행하여 PATH 환경 변수를 다시 로드하고 Cargo의 bin 디렉토리를 포함시키세요:

Terminal
$
. "$HOME/.cargo/env"

설치가 성공적으로 완료되었는지 확인하기 위해 Rust 버전을 확인하세요:

Terminal
$
rustc --version

다음과 같은 출력이 표시되어야 합니다:

rustc 1.86.0 (05f9846f8 2025-03-31)

Solana CLI 설치하기

Solana CLI는 Solana 프로그램을 빌드하고 배포하는 데 필요한 모든 도구를 제공합니다.

공식 설치 명령을 사용하여 Solana CLI 도구 모음을 설치하세요:

Terminal
$
sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"

stable를 원하는 릴리스의 소프트웨어 버전과 일치하는 릴리스 태그(예: v2.0.3)로 대체하거나, 세 가지 심볼릭 채널 이름 중 하나를 사용할 수 있습니다: stable, beta 또는 edge.

Solana CLI를 처음 설치하는 경우, PATH 환경 변수를 추가하라는 다음과 같은 메시지가 표시될 수 있습니다:

Close and reopen your terminal to apply the PATH changes or run the following in your existing shell:
export PATH="/Users/test/.local/share/solana/install/active_release/bin:$PATH"

Linux 또는 WSL을 사용하는 경우, 터미널에서 명령을 사용할 수 있도록 Solana CLI 바이너리를 PATH에 추가해야 합니다.

먼저 다음 명령을 실행하여 어떤 셸을 사용하고 있는지 확인하세요:

Terminal
$
echo $SHELL
  • 출력에 /bash가 포함되어 있으면 .bashrc를 사용하세요.
  • 출력에 /zsh가 포함되어 있으면 .zshrc를 사용하세요.

셸에 따라 적절한 명령을 실행하세요.

Bash(bashrc)의 경우:

Terminal
$
echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.bashrc
$
source ~/.bashrc

Zsh(zshrc)의 경우:

Terminal
$
echo 'export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"' >> ~/.zshrc
$
source ~/.zshrc

그런 다음 터미널 세션을 새로 고치거나 터미널을 다시 시작하기 위해 다음 명령을 실행하세요.

Terminal
$
source ~/.bashrc # If using Bash
$
source ~/.zshrc # If using Zsh

설치가 성공했는지 확인하려면 Solana CLI 버전을 확인하세요:

Terminal
$
solana --version

다음과 같은 출력이 표시되어야 합니다:

solana-cli 2.2.12 (src:0315eb6a; feat:1522022101, client:Agave)

Agave Github 저장소에서 사용 가능한 모든 버전을 볼 수 있습니다.

Agave는 이전에 Solana Labs validator 클라이언트로 알려졌던 Anza의 validator 클라이언트입니다.

나중에 Solana CLI를 최신 버전으로 업데이트하려면 다음 명령어를 사용할 수 있습니다:

Terminal
$
agave-install update

Anchor CLI 설치하기

Anchor는 Solana 프로그램을 개발하기 위한 프레임워크입니다. Anchor 프레임워크는 Rust 매크로를 활용하여 Solana 프로그램 작성 과정을 단순화합니다.

Anchor CLI와 도구를 설치하는 두 가지 방법이 있습니다:

  1. Anchor 버전 관리자(AVM) - 권장 설치 방법
  2. AVM 없이 - GitHub에서 직접 설치

Anchor 버전 관리자(AVM)를 사용하면 시스템에 다양한 Anchor 버전을 설치하고 관리할 수 있으며 향후 Anchor 버전을 쉽게 업데이트할 수 있습니다.

다음 명령어로 AVM을 설치하세요:

Terminal
$
cargo install --git https://github.com/coral-xyz/anchor avm --force

AVM이 성공적으로 설치되었는지 확인하세요:

Terminal
$
avm --version

AVM을 사용하여 최신 버전의 Anchor CLI를 설치하세요:

Terminal
$
avm install latest
$
avm use latest

버전 번호를 지정하여 특정 버전의 Anchor CLI를 설치할 수 있습니다:

Terminal
$
avm install 0.30.1
$
avm use 0.30.1

시스템에서 실행할 Anchor CLI 버전을 선언하기 위해 avm use 명령어를 실행하는 것을 잊지 마세요.

  • latest 버전을 설치했다면, *shellavm use latest*를 실행하세요.
  • 버전 0.30.1를 설치했다면, *shellavm use 0.30.1*를 실행하세요.

설치가 성공했는지 확인하려면 Anchor CLI 버전을 확인하세요:

Terminal
$
anchor --version

다음과 같은 출력이 표시되어야 합니다:

anchor-cli 0.31.1

Linux나 WSL에 Anchor CLI를 설치할 때 다음과 같은 오류가 발생할 수 있습니다:

error: could not exec the linker cc = note: Permission denied (os error 13)

이 오류 메시지가 표시되면:

  1. 이 페이지 상단의 Linux 섹션에 나열된 의존성을 설치하세요.
  2. Anchor CLI 설치를 다시 시도하세요.

Node.js 및 Yarn

anchor init 명령으로 생성된 기본 Anchor 프로젝트 테스트 파일(TypeScript)은 Node.js와 Yarn이 필요합니다. (Rust 테스트 템플릿은 anchor init --test-template rust 를 사용하여 이용 가능합니다)

anchor build를 실행할 때 다음과 같은 오류가 발생하면:

위의 해결책을 적용한 후 anchor build 명령을 다시 실행해 보세요.

Linux나 WSL에서 새로운 Anchor 프로젝트를 생성한 후 *shellanchor test*를 실행할 때 Node.js나 Yarn이 설치되어 있지 않으면 다음과 같은 오류가 발생할 수 있습니다:

Permission denied (os error 13)
No such file or directory (os error 2)

Solana CLI 기본 사항

이 섹션에서는 시작하는 데 도움이 되는 일반적인 Solana CLI 명령어를 안내합니다.

Solana 설정

현재 구성을 확인하려면:

Terminal
$
solana config get

다음과 같은 출력이 표시되어야 합니다:

Config File: /Users/test/.config/solana/cli/config.yml
RPC URL: https://api.mainnet-beta.solana.com
WebSocket URL: wss://api.mainnet-beta.solana.com/ (computed)
Keypair Path: /Users/test/.config/solana/id.json
Commitment: confirmed

RPC URL과 Websocket URL은 CLI가 요청을 보내는 Solana 클러스터를 지정합니다.

다음 명령을 사용하여 Solana CLI 클러스터를 업데이트할 수 있습니다:

Terminal
$
solana config set --url mainnet-beta
$
solana config set --url devnet
$
solana config set --url localhost
$
solana config set --url testnet

다음과 같은 짧은 옵션도 사용할 수 있습니다:

Terminal
$
solana config set -um # For mainnet-beta
$
solana config set -ud # For devnet
$
solana config set -ul # For localhost
$
solana config set -ut # For testnet

Keypair Path는 Solana CLI가 트랜잭션 수수료를 지불하고 프로그램을 배포하는 데 사용하는 기본 Solana 지갑(keypair)을 가리킵니다. 기본적으로 이 파일은 ~/.config/solana/id.json에 저장됩니다.

지갑 생성

Solana CLI를 사용하여 트랜잭션을 보내려면 SOL이 충전된 Solana 지갑이 필요합니다.

기본 Keypair Path에 keypair를 생성하려면 다음 명령을 실행하세요:

Terminal
$
solana-keygen new

다음과 같은 출력이 표시되어야 합니다:

Generating a new keypair
For added security, enter a BIP39 passphrase
NOTE! This passphrase improves security of the recovery seed phrase NOT the
keypair file itself, which is stored as insecure plain text
BIP39 Passphrase (empty for none):
Wrote new keypair to /Users/test/.config/solana/id.json
===========================================================================
pubkey: 8dBTPrjnkXyuQK3KDt9wrZBfizEZijmmUQXVHpFbVwGT
===========================================================================
Save this seed phrase and your BIP39 passphrase to recover your new keypair:
cream bleak tortoise ocean nasty game gift forget fancy salon mimic amazing
===========================================================================

이미 기본 위치에 저장된 파일 시스템 지갑이 있는 경우, --force 플래그를 사용하여 명시적으로 강제 덮어쓰기를 하지 않는 한 이 명령은 기존 지갑을 덮어쓰지 않습니다.

지갑 주소(공개 키)를 보려면 다음을 실행하세요:

Terminal
$
solana address

SOL 에어드롭

트랜잭션 및 프로그램 배포 비용을 지불하기 위해 지갑에 SOL 에어드롭을 요청하세요.

클러스터를 devnet으로 설정하세요:

Terminal
$
solana config set -ud

그런 다음 devnet SOL 에어드롭을 요청하세요:

Terminal
$
solana airdrop 2

Devnet 에어드롭은 요청당 5 SOL로 제한됩니다. 속도 제한에 도달하거나 오류가 발생하면 대신 웹 수도꼭지(Web Faucet)를 사용해 보세요.

지갑의 SOL 잔액을 확인하려면 다음 명령어를 실행하세요:

Terminal
$
solana balance

로컬 validator 실행하기

Solana CLI에는 로컬 개발을 위한 내장 테스트 validator가 포함되어 있습니다.

별도의 터미널에서 다음 명령어를 실행하여 로컬 validator를 시작하세요:

Terminal
$
solana-test-validator

Solana CLI 명령어를 실행하기 전에 CLI를 localhost로 업데이트하는 것을 잊지 마세요:

Terminal
$
solana config set -ul

Anchor CLI 기본 사항

이 섹션에서는 시작하는 데 도움이 되는 몇 가지 일반적인 Anchor CLI 명령어를 살펴봅니다. Anchor CLI에 대한 자세한 정보는 Anchor 문서를 참조하세요.

프로젝트 초기화

새 Anchor 프로젝트를 만들려면 다음 명령어를 실행하세요:

Terminal
$
anchor init <project-name>

예를 들어, my-project 라는 프로젝트를 생성하려면 다음을 실행하세요:

Terminal
$
anchor init my-project

이 명령은 프로젝트 이름으로 새 디렉토리를 생성하고 기본 Rust 프로그램과 TypeScript 테스트 템플릿으로 새 Anchor 프로젝트를 초기화합니다.

프로젝트 디렉토리로 이동하세요:

Terminal
$
cd <project-name>

Anchor 프로젝트의 파일 구조를 확인하세요.

프로그램 빌드하기

프로젝트를 빌드하려면 다음 명령을 실행하세요:

Terminal
$
anchor build

컴파일된 프로그램은 /target/deploy 디렉토리에서 찾을 수 있습니다.

프로그램 배포하기

프로젝트를 배포하려면 다음 명령을 실행하세요:

Terminal
$
anchor deploy

이 명령은 Anchor.toml 파일에 지정된 cluster에 프로그램을 배포합니다.

프로그램 테스트하기

프로젝트를 테스트하려면 다음 명령을 실행하세요:

Terminal
$
anchor test

이 명령은 프로젝트를 빌드하고, 배포하고, 테스트를 실행합니다.

Anchor.toml에서 clusterlocalnet를 사용할 때, Anchor는 자동으로 로컬 validator를 시작하고, 프로그램을 배포하고, 테스트를 실행한 다음 validator를 중지합니다.

Is this page helpful?