qwen code 使用教程

Qwen Code 完全使用教程

📖 目录

• 一、Qwen Code 是什么？

• 二、快速安装

• 三、首次使用与登录

• 四、核心功能一览

• 五、常用命令速查

• 六、日常开发工作流

• 七、高级功能详解

• 八、配置与定制

• 九、实用技巧与最佳实践

• 十、常见问题排查

一、Qwen Code 是什么？

Qwen Code 是通义千问推出的终端 AI 编程助手，具有以下特点：

• ✅直接在终端运行：无需打开额外窗口

• ✅理解整个代码库：自动分析项目结构

• ✅直接编辑文件：可以创建、修改、删除代码文件

• ✅执行命令：运行测试、启动服务器、Git 操作等

• ✅支持 MCP 协议：连接外部数据源（GitHub、Figma 等）

二、快速安装

Windows 用户（推荐）

以管理员身份运行 CMD：

curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat

手动安装（需要 Node.js 20+）

npm install -g @qwen-code/qwen-code@latest

macOS / Linux 用户

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash

提示：安装后建议重启终端以确保环境变量生效。

三、首次使用与登录

1. 启动 Qwen Code

cd your-project qwen

2. 选择认证方式

首次使用会提示登录，选择Qwen OAuth（免费）并按提示完成登录。

3. 验证登录状态

qwen auth status

4. 重新登录（如需）

/auth

登录凭证会自动保存，下次使用无需重复登录。

四、核心功能一览

🎯 1. 理解代码库

获取项目概览：

这个项目是做什么的？

分析目录结构：

explain the folder structure

查找特定功能代码：

find the files that handle user authentication

🛠️ 2. 编写与修改代码

添加新功能：

add a hello world function to the main file

修复 Bug：

there's a bug where users can submit empty forms - fix it

重构代码：

refactor the authentication module to use async/await instead of callbacks

🧪 3. 测试与调试

编写测试：

write unit tests for the calculator functions

运行测试：

run the tests and fix any failures

📝 4. Git 操作

查看更改：

what files have I changed?

提交代码：

commit my changes with a descriptive message

创建分支：

create a new branch called feature/quickstart

解决冲突：

help me resolve merge conflicts

五、常用命令速查

🔧 会话管理

🎨 界面定制

🤖 模型与工具

💾 会话恢复

⚡ 快捷操作

六、日常开发工作流

1️⃣ 理解新项目

# 1. 进入项目目录 cd /path/to/project ​ # 2. 启动 Qwen Code qwen ​ # 3. 请求项目概览 give me an overview of this codebase ​ # 4. 深入了解 explain the main architecture patterns used here what are the key data models? how is authentication handled?

2️⃣ 高效修 Bug

# 1. 描述问题 I'm seeing an error when I run npm test ​ # 2. 请求修复建议 suggest a few ways to fix the error in user.ts ​ # 3. 应用修复 update user.ts to add the null check you suggested ​ # 4. 验证修复 run the tests again

3️⃣ 代码重构

# 1. 识别需要重构的代码 find deprecated API usage in our codebase ​ # 2. 获取重构建议 suggest how to refactor utils.js to use modern JavaScript features ​ # 3. 执行重构 refactor utils.js to use ES 2024 features while maintaining the same behavior ​ # 4. 验证重构 run tests for the refactored code

4️⃣ 编写测试

# 1. 识别未测试的代码 find functions in UserService that are not covered by tests ​ # 2. 生成测试框架 add tests for the user service ​ # 3. 添加边界条件测试 add test cases for edge conditions in the user service ​ # 4. 运行测试 run the new tests and fix any failures

5️⃣ 创建 Pull Request

# 1. 总结更改 summarize the changes I've made to the authentication module ​ # 2. 创建 PR create a pr ​ # 3. 优化描述 enhance the PR description with more context about the security improvements ​ # 4. 添加测试信息 add information about how these changes were tested

七、高级功能详解

🔗 1. 文件和目录引用（@ 命令）

快速引入文件内容到对话中，无需等待 Qwen Code 自动读取：

# 引用单个文件 Explain the logic in @src/utils/auth.js ​ # 引用目录 What's the structure of @src/components? ​ # 引用多个文件 Compare @file1.js and @file2.js

提示：文件路径可以是相对路径或绝对路径。

🤖 2. 审批模式（Approval Mode）

控制 Qwen Code 修改文件的权限：

切换模式：

/approval-mode auto-edit

🌐 3. MCP 协议集成

MCP（Model Context Protocol）允许 Qwen Code 连接外部数据源：

# 查看已配置的 MCP 服务器 /mcp ​ # 使用 MCP 资源 Show me the data from @github: repos/owner/repo/issues

配置 MCP 服务器：在settings.json中添加：

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }

🎯 4. 专用子代理（Sub-agents）

Qwen Code 可以自动使用专门的子代理处理特定任务：

# 查看所有子代理 /agents ​ # 代码审查 review my recent code changes for security issues ​ # 调试 have the debugger subagent investigate why users can't log in ​ # 明确请求特定子代理 use the code-reviewer subagent to check the auth module

创建自定义子代理：

/agents

然后选择"create"，定义：

• 唯一标识符（如code-reviewer）

• 何时使用此代理

• 可访问的工具

• 系统提示词

💻 5. Unix 管道集成

将 Qwen Code 作为 Unix 工具使用：

# 分析错误日志 cat build-error.txt | qwen -p 'explain the root cause of this build error' ​ # 输出到文件 cat build-error.txt | qwen -p 'explain this error' > explanation.txt ​ # 指定输出格式（JSON） cat code.py | qwen -p 'analyze for bugs' --output-format json > analysis.json ​ # 流式 JSON（实时处理） cat log.txt | qwen -p 'find errors' --output-format stream-json

🌳 6. Git Worktrees 并行工作

使用 Git Worktrees 同时运行多个 Qwen Code 会话：

# 创建新的 worktree git worktree add ../project-feature-a -b feature-a ​ # 在 worktree 中运行 Qwen Code cd ../project-feature-a qwen ​ # 在另一个终端打开另一个 worktree cd ../project-bugfix qwen ​ # 管理 worktrees git worktree list git worktree remove ../project-feature-a

八、配置与定制

📁 配置文件位置

⚙️ 常用配置项

{ "model": { "name": "qwen3-coder-plus", "maxSessionTurns": -1, "generationConfig": { "timeout": 300, "temperature": 0.7, "max_tokens": 8192 } }, "ui": { "theme": "dark", "showLineNumbers": true, "compactMode": false }, "general": { "vimMode": false, "enableAutoUpdate": true, "gitCoAuthor": true }, "permissions": { "allow": [ "Bash(npm run *)", "Bash(git *)" ] } }

🎨 主题切换

# 在会话中切换主题 /theme ​ # 或在配置文件中设置 { "ui": { "theme": "dark" } }

九、实用技巧与最佳实践

💡 提示词技巧

✅ DO（推荐）

具体描述问题：

修复登录后 bug：用户输入错误密码后看到空白页面

分步指示：

1. 创建用户配置表 2. 创建 API 端点获取和更新配置 3. 构建允许用户编辑信息的网页

让 Qwen Code 先探索：

先分析数据库结构，然后构建仪表板

❌ DON'T（避免）

过于模糊：

修复 bug

过于复杂：

重构整个认证模块，改用 GraphQL，添加缓存，优化数据库查询，写测试，更新文档，创建 PR

📊 Token 管理

查看使用情况：

/context

节省 Token：

• 使用/compress压缩聊天历史

• 避免过长的对话

• 使用@引用特定文件而非让 Qwen Code 自动探索

压缩阈值配置：

{ "model": { "chatCompression": { "contextPercentageThreshold": 0.7 } } }

🚀 效率提升

1. 使用 Tab 补全：快速完成命令输入

2. 利用历史：按↑键快速访问之前的命令

3. 创建自定义命令：将常用提示词保存为命令

4. 使用计划模式：复杂任务先用/plan分析

5. 开启紧凑模式：Ctrl+O隐藏工具输出，保持界面简洁

📝 创建自定义命令

1. 创建命令文件：

mkdir -p ~/.qwen/commands/review touch ~/.qwen/commands/review/code.md

2. 编辑命令内容：

--- description: 代码审查工具 --- ​ 请审查以下代码，关注： 1. 代码质量 2. 潜在 bug 3. 性能问题 4. 安全漏洞 ​ {{args}}

3. 使用自定义命令：

/review:code @src/auth.js

十、常见问题排查

❌ 问题 1：请求超时

症状：Streaming request timeout after 44s

解决方案：

1. 增加超时时间：

{ "model": { "generationConfig": { "timeout": 300 } } }

1. 压缩上下文：

/compress

1. 减少输入长度：避免一次性引入过多文件

❌ 问题 2：认证失败

症状：无法登录或提示认证错误

解决方案：

# 检查认证状态 qwen auth status ​ # 重新登录 qwen auth ​ # 或在会话内 /auth

❌ 问题 3：命令执行被拒绝

症状：Qwen Code 尝试运行命令时提示需要权限

解决方案：

# 在会话内更改审批模式 /approval-mode auto-edit ​ # 或在配置文件中允许特定命令 { "permissions": { "allow": [ "Bash(npm run *)", "Bash(git *)" ] } }

❌ 问题 4：Token 使用过快

症状：很快就达到上下文限制

解决方案：

1. 使用/compress压缩历史

2. 使用@精确引用文件

3. 减少不必要的探索

4. 配置自动压缩阈值

❌ 问题 5：输出语言不对

症状：Qwen Code 总是用英文回复

解决方案：

# 设置输出语言 /language output Chinese ​ # 或在配置文件中 { "output": { "language": "Chinese" } }

📚 附录

A. 键盘快捷键完整列表

B. 常用提示词模板

代码审查

请审查 @文件路径，关注： 1. 代码质量 2. 潜在 bug 3. 性能问题 4. 是否符合最佳实践

Bug 修复

我发现了一个 bug：[描述 bug] 复现步骤： 1. [步骤 1] 2. [步骤 2] 3. [步骤 3] ​ 请帮我定位并修复这个问题。

功能开发

我需要实现 [功能描述]。 ​ 要求： 1. [要求 1] 2. [要求 2] 3. [要求 3] ​ 请先分析现有代码结构，然后制定实现计划。

文档编写

请为 @文件路径 添加完整的文档注释。 ​ 要求： - 使用 JSDoc 格式 - 包含参数说明 - 包含返回值说明 - 包含使用示例

C. 获取帮助

• 在 Qwen Code 内：输入/help或直接提问

• 官方文档：查阅 Qwen Code 内置文档

• 社区讨论：GitHub Discussions

• 报告问题：/bug [问题描述]

🎓 总结

Qwen Code 是一个强大的 AI 编程助手，能够：

✅理解整个代码库✅直接编辑文件✅执行命令和测试✅协助 Git 操作✅集成外部工具（MCP）✅支持自定义命令和技能

关键使用原则：

1. 🎯具体明确：清晰描述你的需求

2. 📝分步执行：复杂任务拆解为小步骤

3. 🔍先探索后修改：让 Qwen Code 先理解代码

4. 💾保存 Token：适时使用/compress

5. 🔒安全第一：合理设置审批模式

祝您使用愉快！🚀