← Quay lại blog

Cách cấu hình proxy trong Android Studio và Gradle: gradle.properties và SDK Manager

Phân tích cách ghi đúng proxy trong gradle.properties, cấu hình SDK Manager và Android Studio, cũng như khắc phục những lỗi đồng bộ hóa Gradle thường gặp nhất.

📅13 tháng 11, 2026

Nếu Android Studio "đứng" ở giai đoạn đồng bộ Gradle, SDK Manager không tải được các thành phần, và các phụ thuộc từ Maven Central không được tải xuống — trong 80% trường hợp, vấn đề không nằm ở mã nguồn mà nằm ở môi trường mạng. Tường lửa doanh nghiệp, VPN, chặn IP của kho lưu trữ hoặc đơn giản là không có quyền truy cập trực tiếp vào internet — tất cả đều có thể được giải quyết bằng cách cấu hình proxy đúng cách ở ba cấp độ: IDE, Gradle và SDK Manager. Hãy cùng tìm hiểu cách cấu hình proxy một cách chính xác và không gặp phải các lỗi đồng bộ hóa không cần thiết.

Tại sao lập trình viên Android cần proxy

Thường thì proxy được sử dụng kết hợp với Android Studio trong một số kịch bản. Kịch bản đầu tiên — mạng doanh nghiệp, nơi mà quyền truy cập trực tiếp vào internet bị chặn, và toàn bộ lưu lượng, bao gồm cả các yêu cầu đến google(), mavenCentral() và dl.google.com, phải đi qua máy chủ proxy của công ty. Kịch bản thứ hai — vượt qua các hạn chế khu vực: một số thành phần SDK, API Google Play Services hoặc kho lưu trữ bên thứ ba không thể truy cập trực tiếp từ một số quốc gia, và lập trình viên buộc phải định tuyến lưu lượng qua IP của một vị trí địa lý khác.

Kịch bản thứ ba — kiểm tra chức năng phụ thuộc vào địa lý của ứng dụng. Nếu ứng dụng hiển thị nội dung, giá cả hoặc quảng cáo khác nhau tùy thuộc vào quốc gia của người dùng, các kỹ sư QA và lập trình viên cần phải mô phỏng các yêu cầu từ khu vực cần thiết ngay từ giai đoạn xây dựng và gỡ lỗi, không phải đợi đến khi phát hành. Kịch bản thứ tư — làm việc với các runner CI/CD, mà về mặt vật lý nằm trong các trung tâm dữ liệu có quyền truy cập hạn chế đến một số dịch vụ nhất định, và proxy trở thành cách duy nhất để "tiếp cận" đến kho lưu trữ hoặc API cần thiết.

Trong tất cả các trường hợp này, logic là giống nhau: Gradle, SDK Manager và chính IDE cần biết địa chỉ, cổng và, nếu cần, thông tin xác thực của máy chủ proxy, nếu không, quá trình đồng bộ hóa dự án sẽ gặp lỗi với thời gian chờ hoặc lỗi kết nối.

Loại proxy nào nên chọn cho phát triển

Đối với phát triển và kiểm tra, không quan trọng bằng sự ẩn danh mà là sự ổn định của kết nối và tỷ lệ ngắt thấp trong quá trình tải lâu (ví dụ, Android SDK Platform Tools có kích thước hàng trăm megabyte). Dưới đây là bảng so sánh các loại proxy liên quan đến nhiệm vụ của lập trình viên Android.

Loại proxy Khi nào sử dụng Đặc điểm
Proxy trung tâm dữ liệu Tải SDK, đồng bộ Gradle, CI/CD Tốc độ cao, giá thấp, ổn định cho các tải lớn
Proxy cư trú Kiểm tra API và nội dung phụ thuộc vào địa lý IP của người dùng thực, ít bị chặn bởi các dịch vụ
Proxy di động Kiểm tra API di động và thông báo đẩy từ một quốc gia cụ thể IP của nhà mạng, gần giống với lưu lượng di động thực tế

Để đồng bộ hóa Gradle một cách sạch sẽ và tải xuống các phụ thuộc, nên sử dụng proxy trung tâm dữ liệu — chúng cung cấp tốc độ cao ổn định mà không có độ trễ không cần thiết. Nếu nhiệm vụ là kiểm tra cách backend của ứng dụng phản hồi với người dùng từ một quốc gia khác, thì proxy cư trú hoặc IP di động sẽ phù hợp hơn.

Cấu hình proxy trong gradle.properties

Tệp gradle.properties là nơi chính mà Gradle tìm kiếm các cài đặt proxy cho các kết nối HTTP và HTTPS. Tệp này có thể nằm ở thư mục gốc của dự án (chỉ áp dụng cho dự án đó) hoặc trong thư mục toàn cầu ~/.gradle/gradle.properties (áp dụng cho tất cả các dự án trên máy). Để làm việc liên tục qua proxy, nên chọn tùy chọn thứ hai.

# ~/.gradle/gradle.properties

systemProp.http.proxyHost=proxy.example.com
systemProp.http.proxyPort=8080
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080

# tùy chọn — các ngoại lệ sẽ đi trực tiếp, bỏ qua proxy
systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.internal.corp

Sau khi lưu tệp, hãy chắc chắn nhấn File → Sync Project with Gradle Files hoặc biểu tượng "con voi" trên thanh công cụ. Nếu IDE không tự động nhận các thay đổi, hãy khởi động lại Android Studio — đôi khi bộ nhớ cache của cài đặt proxy vẫn giữ lại cho đến khi quá trình Gradle Daemon được khởi động lại.

Một điểm quan trọng: các tham số systemProp.* chỉ có hiệu lực ở cấp độ JVM mà Gradle đang chạy, vì vậy chúng ảnh hưởng không chỉ đến việc tải xuống các phụ thuộc, mà còn đến bất kỳ yêu cầu mạng nào bên trong các tập lệnh xây dựng (ví dụ, nếu bạn có một tác vụ Gradle tùy chỉnh gọi API bên ngoài).

Cấu hình proxy trong chính Android Studio

Ngoài Gradle, IDE còn có các cài đặt mạng riêng — chúng cần thiết cho việc hoạt động của các plugin, cập nhật IDE, kiểm tra giấy phép và một số tính năng như gợi ý từ Google. Bạn có thể mở chúng qua File → Settings → Appearance & Behavior → System Settings → HTTP Proxy (trên macOS — Android Studio → Preferences).

Trong cửa sổ mở ra, chọn Cấu hình proxy thủ công, chỉ định máy chủ và cổng, nếu cần hãy đánh dấu Xác thực proxy và nhập tên đăng nhập cùng mật khẩu. Ở đó cũng có nút tiện lợi Kiểm tra kết nối — nhập URL thử nghiệm (ví dụ, https://dl.google.com) và nhấn nó để đảm bảo rằng kết nối hoạt động chính xác trước khi thực hiện đồng bộ hóa dự án đầy đủ.

Quan trọng là hiểu sự khác biệt

Cài đặt HTTP Proxy trong Cài đặt ảnh hưởng đến chính IDE (plugin, cập nhật), trong khi các tham số trong gradle.properties ảnh hưởng đến quá trình xây dựng Gradle. Đây là hai cơ chế độc lập, và để hoạt động hoàn chỉnh qua proxy, thường cần phải cấu hình cả hai.

Proxy cho SDK Manager

SDK Manager là một thành phần riêng biệt, tải xuống các nền tảng Android, build-tools, trình giả lập và hình ảnh hệ thống. Nó có cấu hình proxy riêng, thường được thiết lập thông qua các cài đặt hệ thống của IDE, nhưng khi làm việc với sdkmanager độc lập (tiện ích CLI từ dòng lệnh), các tham số cần được truyền rõ ràng qua các cờ JVM.

sdkmanager --proxy=http \
  --proxy_host=proxy.example.com \
  --proxy_port=8080 \
  --list

Nếu sdkmanager được khởi chạy qua một tập lệnh, bạn có thể chỉ định proxy ngay trong biến môi trường JAVA_OPTS mà tệp thực thi đọc:

export JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
-Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

Một lỗi thường gặp — cấu hình proxy trong Android Studio nhưng quên các tiện ích độc lập như sdkmanager hoặc avdmanager, mà được khởi chạy trong một quy trình Java riêng và không tự động kế thừa các cài đặt của IDE.

Proxy cho gradlew và biến môi trường

Nếu bạn xây dựng dự án từ terminal thông qua wrapper ./gradlew, bỏ qua IDE (ví dụ, trong CI/CD hoặc chỉ đơn giản là theo thói quen), bạn có thể truyền proxy ngay trong lệnh mà không cần thay đổi gradle.properties:

./gradlew build \
  -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 \
  -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080

Để sử dụng lâu dài, thuận tiện hơn khi đặt biến môi trường GRADLE_OPTS trong hồ sơ shell (.bashrc, .zshrc cho Linux/macOS hoặc biến môi trường Windows):

export GRADLE_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

Điều này đặc biệt hữu ích trong các runner CI như GitHub Actions, GitLab CI hoặc Jenkins, nơi mà các biến môi trường được thiết lập một lần ở cấp độ job và tự động được nhận bởi tất cả các bước xây dựng tiếp theo, mà không cần phải chỉnh sửa các tệp dự án.

Các lỗi đồng bộ hóa thường gặp và cách giải quyết

Hãy cùng phân tích các lỗi thường gặp nhất mà các lập trình viên gặp phải khi cấu hình proxy, và các bước cụ thể để khắc phục chúng.

Lỗi Nguyên nhân Giải pháp
Kết nối đã hết thời gian Proxy không được chỉ định hoặc không khả dụng Kiểm tra host/cổng trong gradle.properties, kiểm tra khả năng truy cập proxy qua curl
407 Cần xác thực Proxy Không cung cấp tên đăng nhập/mật khẩu Thêm systemProp.http.proxyUser và systemProp.http.proxyPassword
Không thể giải quyết máy chủ Phân giải DNS không đi qua proxy Sử dụng socksProxyHost thay vì http cho SOCKS5 với DNS từ xa
Không thể GET 'https://dl.google.com/...' Cài đặt Gradle đã được chỉ định, nhưng trong IDE thì không (hoặc ngược lại) Đồng bộ hóa cài đặt ở cả hai nơi: Cài đặt → HTTP Proxy và gradle.properties
SSL handshake thất bại Proxy chặn SSL (MITM doanh nghiệp) Nhập chứng chỉ gốc của proxy vào cacerts của JDK của bạn

Nếu lỗi xảy ra khi tải xuống các artefact Maven cụ thể (ví dụ, các thư viện androidx.*), việc tạm thời bật log mở rộng của Gradle bằng lệnh ./gradlew build --info sẽ hữu ích — trong đầu ra sẽ thấy được yêu cầu nào đang gặp sự cố và mã phản hồi nào được trả về từ máy chủ.

Proxy có xác thực: tên đăng nhập và mật khẩu

Nếu proxy yêu cầu xác thực (đây là tình huống tiêu chuẩn cho các dịch vụ proxy trả phí và cổng doanh nghiệp), bạn cần thêm hai dòng nữa vào gradle.properties:

systemProp.http.proxyUser=myuser
systemProp.http.proxyPassword=mypassword
systemProp.https.proxyUser=myuser
systemProp.https.proxyPassword=mypassword

Việc lưu mật khẩu proxy dưới dạng văn bản thuần trong tệp gradle.properties của dự án, mà được đưa vào hệ thống kiểm soát phiên bản — là một thực hành xấu. Hãy sử dụng tệp toàn cầu trong thư mục chính của người dùng, không được commit vào Git, hoặc truyền mật khẩu qua các biến môi trường trong giai đoạn CI/CD, để các bí mật không bị rò rỉ vào kho lưu trữ.

Đối với các kịch bản yêu cầu xoay vòng IP (ví dụ, kiểm tra giới hạn API từ các địa chỉ khác nhau), việc sử dụng các dịch vụ proxy với một nhóm địa chỉ sẵn có và một tên đăng nhập duy nhất sẽ thuận tiện hơn — khi đó việc xoay vòng được cấu hình ở phía nhà cung cấp, và trong gradle.properties chỉ cần thay đổi cổng phiên, mà không cần viết lại cấu hình của toàn bộ dự án.

Danh sách kiểm tra chẩn đoán

Nếu sau tất cả các cài đặt mà đồng bộ hóa vẫn gặp sự cố, hãy lần lượt kiểm tra các mục sau:

  • Kiểm tra khả năng truy cập proxy trực tiếp bằng lệnh curl -x http://proxy.example.com:8080 https://dl.google.com
  • Đảm bảo rằng các cài đặt đã được chỉ định cả trong Cài đặt → HTTP Proxy và trong gradle.properties cùng một lúc
  • Xóa bộ nhớ cache của Gradle: ./gradlew --stop và xóa thư mục .gradle/caches
  • Kiểm tra rằng trong tệp không có khoảng trắng và dấu ngoặc kép không cần thiết xung quanh các giá trị host/cổng
  • Nếu sử dụng SOCKS5 — hãy chỉ định socksProxyHost/socksProxyPort thay vì http.proxyHost
  • Đối với các proxy MITM doanh nghiệp, hãy nhập chứng chỉ vào kho chứng chỉ tin cậy của JDK (keytool -import)
  • Khởi động lại Android Studio và Gradle Daemon sau bất kỳ thay đổi nào trong các tệp properties

Kết luận

Cấu hình proxy trong phát triển Android là công việc ở ba cấp độ: cài đặt hệ thống Android Studio cho chính IDE, các tham số systemProp trong gradle.properties cho quá trình xây dựng, và cấu hình riêng cho các tiện ích độc lập như sdkmanager. Hầu hết các lỗi đồng bộ hóa xảy ra chính vì một trong các cấp độ được cấu hình, trong khi cấp độ khác bị bỏ qua, hoặc do thiếu xác thực trên proxy mà yêu cầu xác thực.

Nếu nhiệm vụ chỉ là tải xuống các phụ thuộc và thành phần SDK một cách ổn định qua proxy làm việc, thì proxy trung tâm dữ liệu là lựa chọn tuyệt vời — chúng nhanh và không tạo ra độ trễ không cần thiết khi tải lớn. Còn nếu cần kiểm tra cách ứng dụng hoạt động với người dùng từ một quốc gia cụ thể hoặc từ nhà mạng di động, hãy xem xét proxy cư trú hoặc IP di động — chúng cung cấp cái nhìn thực tế hơn về hành vi của các dịch vụ ở các khu vực khác nhau.