---
# System prepended metadata

title: 使用網頁版 VS Code Server 來執行 Amazon Q CLI

---

# 使用網頁版 VS Code Server 來執行 Amazon Q CLI

## 📋 目錄

1. [概述](#概述)
2. [前置需求](#前置需求)
3. [系統相容性檢查](#系統相容性檢查)
4. [Amazon Q CLI 安裝](#amazon-q-cli-安裝)
5. [故障排除](#故障排除)
6. [最佳實務](#最佳實務)

---

## 概述

本指導手冊基於 [AWS 官方文件](https://docs.aws.amazon.com/zh_tw/amazonq/latest/qdeveloper-ug/command-line-installing-ssh-setup-autocomplete.html)，將教您如何在前面部署的 Docker 容器化多用戶 VS Code Server 環境中正確安裝、配置和使用 Amazon Q CLI。

### 🎯 學習目標

完成本指導手冊後，您將能夠：

- ✅ 檢查系統的 glibc 版本並選擇正確的 Amazon Q CLI 版本
- ✅ 在 Web 版 VS Code Server 中正確安裝 Amazon Q CLI
- ✅ 配置 Amazon Q CLI 的認證和設定
- ✅ 在瀏覽器中的 VS Code 終端機使用 Amazon Q CLI
- ✅ 掌握 Amazon Q CLI 的各種實用功能
- ✅ 解決常見的安裝和使用問題

### 🏗️ 架構概覽

```
┌─────────────────────────────────────────────────────────────┐
│                    瀏覽器 (您的電腦)                        │
│  ┌─────────────────────────────────────────────────────────┤
│  │              VS Code Server Web UI                      │
│  │  ┌──────────────────┐    ┌──────────────────┐          │
│  │  │   檔案管理器     │    │   整合終端機     │          │
│  │  │                  │    │                  │          │
│  │  │   - 專案檔案     │    │   $ q chat       │          │
│  │  │   - 配置檔案     │    │   $ q explain    │          │
│  │  │   - 腳本檔案     │    │   $ q transform  │          │
│  │  └──────────────────┘    └──────────────────┘          │
│  └─────────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────┘
                              │
                              │ HTTPS
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                AWS EC2 Instance (Amazon Linux 2023)        │
│  ┌─────────────────────────────────────────────────────────┤
│  │                Docker Container                         │
│  │  ┌──────────────────────────────────────────────────────┤
│  │  │              Code Server 4.21.1                     │
│  │  │  ┌────────────────┐    ┌────────────────┐           │
│  │  │  │  Amazon Q CLI  │    │  開發環境      │           │
│  │  │  │  (正確版本)    │    │                │           │
│  │  │  │                │    │  - Python 3.11│           │
│  │  │  │  - Standard    │    │  - Node.js 20  │           │
│  │  │  │  - 或 Musl     │    │  - Go 1.21     │           │
│  │  │  │  (依 glibc)    │    │  - Rust        │           │
│  │  │  └────────────────┘    └────────────────┘           │
│  │  └──────────────────────────────────────────────────────┤
│  └─────────────────────────────────────────────────────────┤
└─────────────────────────────────────────────────────────────┘
```

---

## 前置需求

### 🔧 必要條件

在開始之前，請確保您已經完成以下設定：

#### 1. VS Code Server 環境
- ✅ 已部署 Docker 容器化多用戶 VS Code Server
- ✅ 可以透過瀏覽器正常存取 VS Code Server
- ✅ 容器內已安裝基本開發工具和 `unzip` 指令

#### 2. AWS 帳戶與權限
- ✅ 有效的 AWS 帳戶
- ✅ Amazon Q Developer 的存取權限
- ✅ 適當的 IAM 權限設定

#### 3. 網路連線
- ✅ 穩定的網際網路連線
- ✅ 可以存取 AWS 服務的網路環境

### 📋 檢查清單

在開始安裝前，請執行以下檢查：

```bash
# 1. 檢查 VS Code Server 狀態
curl -I http://your-server-ip:8080

# 2. 登入到容器
docker exec -it vscode-apple /bin/bash

# 3. 檢查基本工具
python3 --version
node --version
curl --version
unzip -v
```

---

## 系統相容性檢查

> **📋 適用對象**：本章節主要提供給 **VS Code Server 系統管理員** 參考，用於在部署或維護容器環境時進行系統相容性評估。

根據 AWS 官方文件，Amazon Q CLI 的安裝需要先檢查系統相容性。

### 🔍 支援的系統

Amazon Q CLI 支援以下系統：

- **Fedora** 最新發行版本
- **Ubuntu** 最新發行版本  
- **Amazon Linux 2023** 最新發行版本
- **架構**: 64 位元 x86_64 和 ARM aarch64

### 📊 檢查 glibc 版本

**這是最重要的步驟！** 您需要檢查系統的 glibc 版本來決定使用哪個版本的 Amazon Q CLI。

#### 1. 進入 VS Code Server

首先，在瀏覽器中開啟您的 VS Code Server：

```
http://your-server-ip:8080  (apple 用戶)
http://your-server-ip:8081  (orange 用戶)
```

#### 2. 開啟整合終端機

在 VS Code Server 中：
- 按下 `Ctrl + Shift + `` (反引號) 或
- 選擇選單 `Terminal` → `New Terminal`

#### 3. 檢查 glibc 版本

在終端機中執行：

```bash
# 檢查 glibc 版本
ldd --version
```

輸出範例：

```bash
# Amazon Linux 2023 (通常是 2.34+)
ldd (GNU libc) 2.34
Copyright (C) 2021 Free Software Foundation, Inc.

# 或者較舊的系統 (< 2.34)
ldd (GNU libc) 2.28
Copyright (C) 2018 Free Software Foundation, Inc.
```

#### 4. 版本判斷規則

根據檢查結果：

- **glibc 2.34 或更新版本** → 使用 **標準版本**
- **glibc 版本早於 2.34** → 使用 **Musl 版本**

#### 5. 檢查系統架構

```bash
# 檢查系統架構
uname -m
```

可能的輸出：
- `x86_64` → 使用 x86-64 版本
- `aarch64` → 使用 ARM 版本

### 📋 相容性檢查總結

執行以下腳本來自動檢查您的系統：

```bash
#!/bin/bash
echo "=== Amazon Q CLI 系統相容性檢查 ==="
echo

# 檢查作業系統
echo "作業系統資訊:"
cat /etc/os-release | grep -E "(NAME|VERSION)"
echo

# 檢查架構
ARCH=$(uname -m)
echo "系統架構: $ARCH"

# 檢查 glibc 版本
echo "glibc 版本檢查:"
GLIBC_VERSION=$(ldd --version | head -n1 | grep -o '[0-9]\+\.[0-9]\+')
echo "glibc 版本: $GLIBC_VERSION"

# 判斷需要的版本
if [ "$(echo "$GLIBC_VERSION >= 2.34" | bc -l 2>/dev/null)" = "1" ] || [ "$GLIBC_VERSION" \> "2.34" ] || [ "$GLIBC_VERSION" = "2.34" ]; then
    VERSION_TYPE="標準版本"
    FILE_SUFFIX=""
else
    VERSION_TYPE="Musl 版本"
    FILE_SUFFIX="-musl"
fi

echo
echo "=== 建議的 Amazon Q CLI 版本 ==="
echo "版本類型: $VERSION_TYPE"

if [ "$ARCH" = "x86_64" ]; then
    echo "下載檔案: q-x86_64-linux${FILE_SUFFIX}.zip"
elif [ "$ARCH" = "aarch64" ]; then
    echo "下載檔案: q-aarch64-linux${FILE_SUFFIX}.zip"
else
    echo "警告: 不支援的架構 $ARCH"
fi

# 檢查必要工具
echo
echo "=== 必要工具檢查 ==="
for tool in curl unzip; do
    if command -v $tool >/dev/null 2>&1; then
        echo "✓ $tool: 已安裝"
    else
        echo "✗ $tool: 未安裝"
    fi
done
```

將此腳本儲存為 `check-compatibility.sh` 並執行：

```bash
chmod +x check-compatibility.sh
./check-compatibility.sh
```

---

## Amazon Q CLI 安裝

> **👤 適用對象**：本章節適合 **Amazon Q CLI 用戶** 參考，提供完整的安裝和配置流程。

根據 AWS 官方文件，以下是正確的安裝步驟。

### 🔧 步驟 1：安裝必要工具

在開始下載和安裝 Amazon Q CLI 之前，需要確保系統已安裝必要的工具。

#### 檢查必要工具

```bash
# 檢查是否已安裝必要工具
for tool in curl unzip; do
    if command -v $tool >/dev/null 2>&1; then
        echo "✓ $tool: 已安裝"
    else
        echo "✗ $tool: 未安裝"
    fi
done
```

#### 安裝解壓縮工具

根據您的作業系統選擇適當的安裝指令：

##### Amazon Linux 2023

```bash
# 更新套件列表
sudo dnf update -y

# 安裝 unzip 和 curl (通常已預安裝)
sudo dnf install -y unzip curl

# 驗證安裝
unzip -v
curl --version
```

##### Ubuntu / Debian

```bash
# 更新套件列表
sudo apt-get update

# 安裝 unzip 和 curl
sudo apt-get install -y unzip curl

# 驗證安裝
unzip -v
curl --version
```

##### CentOS / RHEL / Fedora

```bash
# CentOS/RHEL 7/8
sudo yum update -y
sudo yum install -y unzip curl

# 或者 Fedora/CentOS Stream/RHEL 9+
sudo dnf update -y
sudo dnf install -y unzip curl

# 驗證安裝
unzip -v
curl --version
```

##### Alpine Linux

```bash
# 更新套件索引
sudo apk update

# 安裝 unzip 和 curl
sudo apk add unzip curl

# 驗證安裝
unzip -v
curl --version
```

#### 在 Docker 容器中安裝

如果您在 Docker 容器中，可能需要以 root 權限安裝：

```bash
# 檢查當前用戶
whoami

# 如果是 root 用戶，直接安裝
apt-get update && apt-get install -y unzip curl

# 如果是一般用戶，使用 sudo
sudo apt-get update && sudo apt-get install -y unzip curl
```

### 📥 步驟 2：下載安裝檔案

根據前面的相容性檢查結果，選擇適當的下載指令：

#### 標準版本 (glibc 2.34+)

##### Linux x86-64

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" \
  -o "q.zip"
```

##### Linux ARM (aarch64)

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-aarch64-linux.zip" \
  -o "q.zip"
```

#### Musl 版本 (適用於 glibc < 2.34)

##### Linux x86-64 搭配 musl

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip" \
  -o "q.zip"
```

##### Linux ARM (aarch64) 搭配 musl

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-aarch64-linux-musl.zip" \
  -o "q.zip"
```

### 🔧 步驟 3：安裝 Amazon Q CLI

按照 AWS 官方文件的步驟進行安裝：

#### 1. 解壓縮安裝程式

```bash
# 解壓縮下載的檔案
unzip q.zip
```

您應該會看到類似以下的輸出：

```bash
Archive:  q.zip
   creating: q/
  inflating: q/install.sh
  inflating: q/q
  inflating: q/LICENSE
  inflating: q/README.md
```

#### 2. 執行安裝程式

```bash
# 執行官方安裝腳本
./q/install.sh
```

安裝程式會啟動互動式設定流程，以下是完整的安裝過程：

##### 步驟 1：Shell 配置選擇

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
? Do you want q to modify your shell config (you will have to manually do this otherwise)? ›
❯ Yes
  No
```

**建議選擇 `Yes`**，讓安裝程式自動修改您的 shell 配置檔案。

##### 步驟 2：登入方式選擇

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
? Select login method ›
  Use for Free with Builder ID
❯ Use with Pro license
```

選擇適合您的登入方式：
- **Use for Free with Builder ID**: 免費版本，使用 AWS Builder ID
- **Use with Pro license**: 專業版本，使用企業 SSO 或 AWS 帳戶

##### 步驟 3：輸入 Start URL（如選擇 Pro license）

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
? Enter Start URL › https://d-9911abacfd.awsapps.com/start
```

輸入您組織的 AWS SSO Start URL，格式通常為：
`https://your-org.awsapps.com/start`

**Enter Start URL ›** 提示時，請輸入您組織的完整 SSO URL。

##### 步驟 4：選擇 AWS 區域

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9911abacfd.awsapps.com/start
? Enter Region › us-east-1
```

選擇適當的 AWS 區域，Amazon Q CLI 目前支援的區域：
- `us-east-1` (美國東部 - 維吉尼亞北部)
- `eu-central-1` (歐洲 - 法蘭克福)

**Enter Region ›** 提示時，請選擇上述支援的區域之一。

##### 步驟 5：瀏覽器認證

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9911abacfd.awsapps.com/start
✔ Enter Region · us-east-1

Confirm the following code in the browser
Code: LSRC-XPGB

Open this URL: https://d-9911abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
▰▰▰▰▰▰▱ Logging in...
```

**重要步驟**：
1. 複製顯示的 URL 到您本地電腦的瀏覽器
2. 在瀏覽器中輸入顯示的驗證碼（例如：`LSRC-XPGB`）
3. 完成 AWS SSO 登入流程
4. 等待認證完成

##### 步驟 6：安裝完成

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9911abacfd.awsapps.com/start
✔ Enter Region · us-east-1

Confirm the following code in the browser
Code: LSRC-XPGB

Open this URL: https://d-9911abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
Device authorized

Logged in successfully
```

當看到 `Device authorized` 和 `Logged in successfully` 訊息時，表示安裝和認證都已完成。

#### 3. 重新載入環境變數

由於安裝程式已自動修改 shell 配置，需要重新載入環境變數：

```bash
# 重新載入 shell 配置
source ~/.bashrc

# 或者重新開啟終端機
```

#### 4. 驗證安裝和認證

安裝完成後，執行 `q chat` 指令來驗證 Amazon Q CLI 是否成功安裝並可正常使用：

```bash
# 執行 q chat 指令驗證安裝
q chat
```

如果安裝和認證都成功，您將看到 Amazon Q CLI 的歡迎畫面：

```bash
coder@c0a265769ffc:~/workspace$ q chat

    ⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
 ⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⢀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
 ⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠘⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀⢸⣿⣿
 ⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀⠀⢸⣿⡿
 ⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
 ⠚⠛⠋⠀⠀⠀⠀⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀⠀⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠿⢿⡧

╭─────────────────────────────── Did you know? ────────────────────────────────╮
│                                                                              │
│        You can enable custom tools with MCP servers. Learn more with         │
│                                    /help                                     │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

/help all commands  •  ctrl + j new lines  •  ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-4-sonnet

> 
```

當您看到上述的 Amazon Q 標誌和互動式聊天介面時，表示：

- ✅ **Amazon Q CLI 安裝成功**
- ✅ **認證配置正確**
- ✅ **可以正常使用 Amazon Q 服務**
- ✅ **準備開始與 AI 助手對話**

### 📝 驗證成功指標

如果您看到以下元素，表示安裝驗證成功：

1. **ASCII 藝術標誌**: Amazon Q 的視覺標誌
2. **提示訊息**: "Did you know?" 資訊框
3. **快捷鍵說明**: `/help all commands • ctrl + j new lines • ctrl + s fuzzy search`
4. **模型資訊**: `🤖 You are chatting with claude-4-sonnet`
5. **輸入提示**: `>` 符號等待您的輸入

### 🎯 開始使用

現在您可以開始與 Amazon Q 對話：

```bash
> 你好，Amazon Q！請介紹一下你的功能

> 如何在 Python 中讀取 CSV 檔案？

> 請解釋什麼是 Docker 容器
```

要退出聊天模式，可以使用 `Ctrl + C` 或輸入 `/quit`。

### 📝 安裝注意事項

#### 如果選擇 "Use for Free with Builder ID"

如果您在步驟2選擇了免費版本，安裝流程會略有不同：

```bash
coder@c0a265769ffc:~/workspace$ ./q/install.sh
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use for Free with Builder ID

Confirm the following code in the browser
Code: ABCD-EFGH

Open this URL: https://signin.aws.amazon.com/oauth?response_type=device_code&client_id=...
▰▰▰▰▰▰▱ Logging in...

Device authorized
Logged in successfully
```

#### 瀏覽器認證步驟詳解

由於您在容器中運行 Amazon Q CLI，瀏覽器認證需要特別注意：

1. **複製 URL**: 從終端機複製完整的認證 URL
2. **本地瀏覽器**: 在您本地電腦（不是容器內）的瀏覽器中開啟 URL
3. **輸入驗證碼**: 在瀏覽器頁面中輸入終端機顯示的驗證碼
4. **完成登入**: 根據選擇的登入方式完成 AWS SSO 或 Builder ID 登入
5. **等待確認**: 回到終端機等待 "Device authorized" 訊息

#### 常見問題處理

##### 問題：驗證碼過期

```bash
Error: The device code has expired. Please try again.
```

**解決方案**: 重新執行安裝程式，並在驗證碼過期前完成瀏覽器認證。

##### 問題：無法開啟瀏覽器

```bash
Error: Unable to open browser automatically
```

**解決方案**: 手動複製 URL 到瀏覽器，這在容器環境中是正常的。

##### 問題：認證失敗

```bash
Error: Authentication failed
```

**解決方案**: 
1. 檢查網路連線
2. 確認 Start URL 正確
3. 驗證 AWS SSO 權限
4. 重新執行安裝程式





---

## 故障排除

### 🔧 常見問題與解決方案

#### 1. 安裝問題

##### 問題：下載失敗

```bash
# 錯誤訊息
curl: (7) Failed to connect to desktop-release.q.us-east-1.amazonaws.com port 443: Connection refused
```

**解決方案**：

```bash
# 檢查網路連線
ping desktop-release.q.us-east-1.amazonaws.com

# 檢查防火牆設定
sudo iptables -L

# 使用替代方式下載
wget "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip"
```

##### 問題：glibc 版本不相容

```bash
# 錯誤訊息
./q: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found
```

**解決方案**：

```bash
# 重新檢查 glibc 版本
ldd --version

# 如果版本 < 2.34，使用 Musl 版本
curl --proto '=https' --tlsv1.2 -sSf \
  "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip" \
  -o "q.zip"

# 重新安裝
unzip q.zip
./q/install.sh
```

##### 問題：權限不足

```bash
# 錯誤訊息
Permission denied: ~/.local/bin/q
```

**解決方案**：

```bash
# 檢查目錄權限
ls -la ~/.local/bin/

# 修復權限
chmod +x ~/.local/bin/q

# 或重新安裝到用戶目錄
mkdir -p ~/.local/bin
cp q/q ~/.local/bin/
chmod +x ~/.local/bin/q
```

#### 2. 認證問題

##### 問題：需要重新登入 Amazon Q CLI

當您遇到認證相關問題時，可以使用以下步驟重新登入：

**步驟 1：登出當前會話**

```bash
# 登出 Amazon Q CLI
q logout
```

輸出範例：
```bash
coder@c0a265769ffc:~/workspace$ q logout
You are now logged out
Run q login to log back in to Amazon Q
```

**步驟 2：重新登入流程**

執行登入指令並選擇登入方式：

```bash
# 重新登入 Amazon Q CLI
q login
```

**步驟 2-1：Shell 配置選擇**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
? Select login method ›
  Use for Free with Builder ID
❯ Use with Pro license
```

**步驟 2-2：輸入 Start URL**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
? Enter Start URL › https://d-9099abacfd.awsapps.com/start
```

**步驟 2-3：選擇 AWS 區域**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9099abacfd.awsapps.com/start
? Enter Region › us-east-1
```

**步驟 2-4：瀏覽器認證**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9099abacfd.awsapps.com/start
✔ Enter Region · us-east-1

Confirm the following code in the browser
Code: LSRC-XPGB

Open this URL: https://d-9099abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
▰▰▰▰▰▰▱ Logging in...
```

**步驟 2-5：完成認證**
```bash
coder@c0a265769ffc:~/workspace$ q login
✔ Do you want q to modify your shell config (you will have to manually do this otherwise)? · Yes
✔ Select login method · Use with Pro license
✔ Enter Start URL · https://d-9099abacfd.awsapps.com/start
✔ Enter Region · us-east-1

Confirm the following code in the browser
Code: LSRC-XPGB

Open this URL: https://d-9099abacfd.awsapps.com/start/#/device?user_code=LSRC-XPGB
Device authorized

Logged in successfully
```

**重要提醒**：
- 在步驟 2-4 中，需要在本地電腦的瀏覽器中開啟顯示的 URL
- 輸入顯示的驗證碼（例如：LSRC-XPGB）
- 完成 AWS SSO 登入流程
- 等待 "Device authorized" 和 "Logged in successfully" 訊息

#### 3. 功能問題

##### 問題：指令無法執行

```bash
# 錯誤訊息
q: command not found
```

**解決方案**：

```bash
# 檢查 PATH 環境變數
echo $PATH

# 檢查安裝位置
ls -la ~/.local/bin/q

# 重新設定 PATH
export PATH="/home/coder/.local/bin:$PATH"
echo 'export PATH="/home/coder/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

### 🔍 除錯工具

#### 1. 詳細日誌

```bash
# 啟用詳細日誌
export Q_CLI_DEBUG=true
q chat "test message"

# 查看日誌檔案
tail -f ~/.aws/q/logs/q-cli.log

# 設定日誌等級
export Q_CLI_LOG_LEVEL=DEBUG
```

#### 2. 系統診斷腳本

```bash
#!/bin/bash
# q-cli-diagnostic.sh - Amazon Q CLI 診斷腳本

echo "=== Amazon Q CLI 診斷報告 ==="
echo "生成時間: $(date)"
echo

echo "=== 系統資訊 ==="
echo "作業系統: $(cat /etc/os-release | grep PRETTY_NAME | cut -d'"' -f2)"
echo "架構: $(uname -m)"
echo "glibc 版本: $(ldd --version | head -n1)"
echo

echo "=== Amazon Q CLI 狀態 ==="
if command -v q >/dev/null 2>&1; then
    echo "✓ Amazon Q CLI: 已安裝"
    echo "版本: $(q --version)"
    echo "位置: $(which q)"
else
    echo "✗ Amazon Q CLI: 未安裝或不在 PATH 中"
fi
echo

echo "=== 環境變數 ==="
echo "PATH: $PATH"
env | grep -E "(AWS|Q_CLI)" || echo "無相關環境變數"
echo

echo "=== 認證狀態 ==="
echo "請使用 'q login' 來檢查和設定認證狀態"
echo

echo "=== 網路連線測試 ==="
if ping -c 1 desktop-release.q.us-east-1.amazonaws.com >/dev/null 2>&1; then
    echo "✓ 可以連接到 Amazon Q 服務"
else
    echo "✗ 無法連接到 Amazon Q 服務"
fi
echo

echo "=== 檔案權限 ==="
if [ -f ~/.local/bin/q ]; then
    ls -la ~/.local/bin/q
else
    echo "Amazon Q CLI 執行檔不存在"
fi

if [ -d ~/.aws ]; then
    echo "AWS 配置目錄權限:"
    ls -la ~/.aws/
else
    echo "AWS 配置目錄不存在"
fi
```

將此腳本儲存為 `q-cli-diagnostic.sh` 並執行：

```bash
chmod +x q-cli-diagnostic.sh
./q-cli-diagnostic.sh
```

---

## 最佳實務

### 🎯 使用建議

#### 1. 有效的提問技巧

##### 具體明確的問題

```bash
# ❌ 不好的問題
q chat "我的程式碼有問題"

# ✅ 好的問題
q chat "這個 Python 函數在處理大型列表時記憶體使用過高，如何優化？" --context slow_function.py
```

##### 提供充足的上下文

```bash
# ❌ 缺乏上下文
q chat "如何修復這個錯誤？"

# ✅ 提供完整上下文
q chat "在執行 Django 遷移時出現 'relation already exists' 錯誤，如何解決？" --context error.log
```

#### 2. 定期維護

```bash
# 檢查更新
q --version

# 清理快取
rm -rf ~/.aws/q/cache/

# 重新登入以更新認證
q logout && q login
```

#### 3. 安全性最佳實務

```bash
# 定期重新登入以更新憑證
q logout && q login

# 避免在程式碼中硬編碼憑證
q chat "如何安全地管理應用程式中的 API 金鑰？"

# 使用最小權限原則
# 在 IAM 中只授予必要的 Amazon Q 權限
```

### 📈 效率提升技巧

#### 1. 自動化工作流程

建立自動化腳本：

```bash
#!/bin/bash
# q-workflow.sh - 自動化程式碼審查工作流程

echo "開始自動化程式碼審查..."

# 審查所有 Python 檔案
for file in *.py; do
    if [ -f "$file" ]; then
        echo "審查 $file..."
        q review "$file" > "review_$file.md"
    fi
done

# 生成改進建議
q chat "基於這些審查報告，提供整體改進建議" --context review_*.md > improvement_suggestions.md

echo "工作流程完成！檢查 improvement_suggestions.md"
```

#### 2. VS Code Server 整合最佳實務

在 VS Code Server 中建立 `.vscode/settings.json`：

```json
{
    "terminal.integrated.defaultProfile.linux": "bash",
    "terminal.integrated.profiles.linux": {
        "bash": {
            "path": "/bin/bash",
            "args": ["-l"],
            "env": {
                "Q_CLI_AUTO_PROMPT": "true"
            }
        }
    },
    "terminal.integrated.cwd": "${workspaceFolder}"
}
```

建立 `.vscode/tasks.json`：

```json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Q Review Current File",
            "type": "shell",
            "command": "q",
            "args": ["review", "${file}"],
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared"
            }
        },
        {
            "label": "Q Explain Current File",
            "type": "shell",
            "command": "q",
            "args": ["explain", "${file}"],
            "group": "build"
        }
    ]
}
```

---

## 總結

### 🎯 本指導手冊總結

本指導手冊基於 AWS 官方文件，提供了在 Docker 容器化 VS Code Server 環境中安裝和使用 Amazon Q CLI 的完整指南：

#### ✅ 核心成就
- **正確的版本選擇**: 根據 glibc 版本選擇標準版本或 Musl 版本
- **官方安裝流程**: 遵循 AWS 官方文件的安裝步驟
- **完整的配置指南**: 涵蓋多種認證方式的詳細設定
- **實用的整合技巧**: 在 Web 版 VS Code Server 中的最佳使用方式

#### ✅ 關鍵特色
- **系統相容性檢查**: 自動檢測系統並選擇正確版本
- **詳細的故障排除**: 涵蓋常見問題和解決方案
- **最佳實務指導**: 提升開發效率的實用技巧

### 🚀 使用優勢

#### 在 Web 版 VS Code Server 中使用 Amazon Q CLI 的優勢：
- **隨時隨地存取**: 透過瀏覽器即可使用完整的 AI 助手功能
- **統一開發環境**: 所有團隊成員使用相同的工具和配置
- **容器化隔離**: 每個用戶獨立的開發環境，避免衝突
- **雲端整合**: 與 AWS 服務的無縫整合

### 💡 持續改進建議

1. **定期更新**: 保持 Amazon Q CLI 的最新版本
2. **監控使用**: 定期檢查認證狀態和使用情況
3. **學習新功能**: 關注 Amazon Q CLI 的新功能和改進
4. **分享經驗**: 與團隊分享使用技巧和最佳實務

### 📚 參考資源

- [AWS 官方文件 - Amazon Q CLI 安裝](https://docs.aws.amazon.com/zh_tw/amazonq/latest/qdeveloper-ug/command-line-installing-ssh-setup-autocomplete.html)
- [Amazon Q Developer 使用者指南](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/)
- [AWS CLI 配置指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)

---

*最後更新：2025年8月3日*  
*作者：James Chan*  
*適用於：Amazon Linux 2023, Docker 24.0+, VS Code Server 4.21.1, Amazon Q CLI 最新版*
