适用环境：macOS / Windows / Linux + Node.js 16.0+ + Git
目标：在 GitHub Pages 上搭建 Hexo 静态博客，实现「写文章 → 推送源码 → 自动构建并部署」的全自动化工作流

概述

静态博客方案结合了 Markdown 的写作体验和 GitHub Pages 的免费托管能力，是个人技术博客和知识库的首选方案之一。Hexo 作为最流行的静态博客框架，生态成熟、主题丰富、部署方式灵活，社区中积累了大量开箱即用的主题和插件。

本文以一个真实的生产环境博客（伞间岁月）为案例，详细讲解：

• Hexo 项目的初始化和核心配置
• 主题选择与定制要点
• GitHub Actions 自动化部署流水线的完整搭建
• 自定义域名与 CDN 加速
• 日常写作工作流和问题排查

一、整体架构

静态博客方案的核心思想是 源码与静态文件分离：源码仓库存放 Hexo 源文件（Markdown 文章、主题、配置），GitHub Pages 仓库只存放构建后的 HTML/CSS/JS。两者通过 GitHub Actions 自动同步。

                    Hexo 源码仓库            github.com/你的用户名/blog-source  _posts/        themes/        _config.yml     .github/  文章.md        主题文件         package         workflows/                                .json           deploy.yml                      │ git push (main 分支)                      ▼                    GitHub Actions  1. actions/checkout@v3 → 拉取源码  2. 安装 Node.js + npm ci  3. hexo generate → 构建静态文件  4. 推送 public/ 到 Pages 仓库的 gh-pages 分支                      │ 自动部署                      ▼                   GitHub Pages 仓库        github.com/你的用户名/你的用户名.github.io  gh-pages 分支：index.html, archives/, posts/, ...                      │ GitHub Pages 服务                      ▼                    https://你的域名/

这种架构的优势：

• 职责清晰：源文件和构建产物互不干扰
• 安全可控：源码仓库可设为 Private，Pages 仓库保持 Public
• 零成本运维：GitHub Pages + Actions 的免费额度对个人博客绰绰有余
• 全自动化：一次配置，永久生效，只管写作和推送

二、前置准备

2.1 安装 Node.js

Hexo 基于 Node.js，首先确保系统已安装 Node.js 16.0+：

# macOSbrew install node# Windows（推荐使用 nvm-windows 或直接下载安装包）# https://nodejs.org/# Linuxcurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -sudo apt-get install -y nodejs# 验证版本node -vnpm -v

2.2 安装 Git 并配置 SSH

# macOSbrew install git# Windows: https://git-scm.com/download/win# Linux: sudo apt-get install git# 配置全局身份信息git config --global user.name "你的 GitHub 用户名"git config --global user.email "你的邮箱@example.com"# 生成 SSH 密钥对ssh-keygen -t ed25519 -C "你的邮箱@example.com"# 查看并复制公钥cat ~/.ssh/id_ed25519.pub

将输出的公钥添加到 GitHub → Settings → SSH and GPG keys → New SSH key。

SSH 的详细配置（包括多账号、权限问题排查）可参考同系列的 《微信小程序 Git 远程仓库设置》。

2.3 创建两个 GitHub 仓库

需要准备两个仓库：

命名说明：如果你的站点是用户级 Pages（https://你的用户名.github.io），Pages 仓库必须命名为 你的用户名.github.io。如果是项目级 Pages（https://你的用户名.github.io/仓库名/），仓库名可以任意。

三、初始化 Hexo 项目

3.1 安装 Hexo CLI

npm install -g hexo-cli

3.2 创建项目

# 在目标目录创建 Hexo 项目hexo init blog-sourcecd blog-source# 安装项目依赖npm install

hexo init 生成的目录结构：

blog-source/├── _config.yml        # 站点配置文件——最重要的配置文件├── package.json       # Node.js 依赖声明├── node_modules/      # 依赖包（不提交到 Git）├── scaffolds/         # 文章模板（可自定义）├── source/            # 源文件目录│   ├── _posts/        # 博客文章（Markdown 文件）│   └── CNAME          # 自定义域名文件（可选）├── themes/            # 主题目录└── public/            # 构建输出（自动生成，不提交）

3.3 安装常用插件

npm install hexo-abbrlink hexo-generator-feed --save

各插件作用：

四、站点配置

4.1 编辑 _config.yml

项目根目录的 _config.yml 是 Hexo 的核心配置文件。以下是关键配置项：

# ===== 站点信息 =====title: 我的博客subtitle: '副标题'description: '博客描述，用于 SEO'author: 你的名字language: zh-CNtimezone: ''# ===== URL 配置 =====url: https://你的域名.com                         # 博客最终访问地址permalink: posts/:abbrlink/                       # 使用 abbrlink 短链接permalink_defaults:pretty_urls:  trailing_index: false                           # 去除 index.html# ===== 目录配置 =====source_dir: sourcepublic_dir: publictag_dir: tagsarchive_dir: archivescategory_dir: categories# ===== 写作配置 =====syntax_highlighter: false       # 关闭内置高亮（交给主题处理）highlight:  enable: falseprismjs:  enable: false# ===== 首页分页 =====index_generator:  per_page: 10  order_by: -date# ===== 文章短链接（hexo-abbrlink）=====abbrlink:  alg: crc32                    # 算法：crc16（更短）或 crc32（更唯一）  reps: true                    # 使用数字 + 字母混合# ===== RSS Feed =====feed:  type: atom  path: atom.xml  limit: 20  order_by: -date

4.2 初始化 Git 并推送到远程

git initgit add .git commit -m "feat: init hexo blog"git remote add origin git@github.com:你的用户名/blog-source.gitgit branch -M maingit push -u origin main

五、主题配置

5.1 选择主题

Hexo 拥有丰富的主题生态，可通过 Hexo Themes 官方列表 浏览。以下是社区中活跃度较高的主题：

5.2 安装主题

以 Keep 主题为例：

git clone https://github.com/theme-keep/hexo-theme-keep.git themes/keep

在 _config.yml 中启用：

theme: keep

5.3 主题配置方式（重要）

每个主题都有自己的配置项，有两种配置方式：

方式一（推荐）：在项目根目录创建 _config.{主题名}.yml，Hexo 会自动合并此文件的内容到主题默认配置之上。这样做的好处是避免直接修改 themes/ 目录下的文件，方便以后升级主题。

# _config.keep.ymlmenu:  首页: /  归档: /archives/  分类: /categories/  标签: /tags/favicon: /images/favicon.pngavatar: /images/avatar.jpgsocial:  GitHub: https://github.com/你的用户名

方式二：直接编辑 themes/keep/_config.yml（不推荐，升级主题时会覆盖）。

主题渲染器依赖：部分主题需要额外的渲染器。Keep 主题需要 hexo-renderer-ejs 和 hexo-renderer-stylus，Butterfly 需要 hexo-renderer-pug。安装主题时请阅读其文档确认。

六、GitHub Actions 自动化部署

这是本方案的核心环节。配置完成后，你只需要 git push 源码，博客便会自动构建并部署。

6.1 部署流程概览

你写文章 → git push → GitHub Actions 触发 →  → Checkout 源码 → 安装依赖 → hexo generate →  → 推送 public/ 到 Pages 仓库 → GitHub Pages 生效

6.2 创建 GitHub Personal Access Token

GitHub Actions 需要权限将构建产物推送到 Pages 仓库：

1. 打开 GitHub → 右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. 点击 Generate new token (classic)
3. Note：填写 HEXO_DEPLOY（方便识别）
4. Expiration：选择 No expiration（永不过期），或选择 90 天并在过期前刷新
5. Scopes：勾选 repo（Full control of private repositories）——这包含了将文件推送到仓库所需的所有权限
6. 点击底部的 Generate token
7. 立即复制并保存生成的 Token（关闭页面后将无法再次查看）

6.3 将 Token 添加到源码仓库 Secrets

1. 打开你的源码仓库 → Settings → Secrets and variables → Actions
2. 点击 New repository secret
3. Name：HEXO_DEPLOY（必须与 workflow 文件中引用的名称一致）
4. Secret：粘贴上一步保存的 Token
5. 点击 Add secret

6.4 创建 Workflow 文件

在项目根目录创建 .github/workflows/hexo-deploy.yml：

name: deploying Hexo project to GitHub pageson:  push:    branches:      - main  # 当 main 分支有推送时触发jobs:  build-and-deploy:    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v3        with:          fetch-depth: 0      - name: Build and Deploy        uses: theme-keep/hexo-deploy-github-pages-action@master        env:          PERSONAL_TOKEN: ${{ secrets.HEXO_DEPLOY }}          PUBLISH_REPOSITORY: 你的用户名/你的Pages仓库名          BRANCH: gh-pages          PUBLISH_DIR: ./public

关键配置项说明：

这个 Action 会自动完成以下步骤：

1. 拉取源码仓库的最新代码
2. 安装 Node.js（内置使用 Node 18）
3. 执行 npm ci 安装依赖（比 npm install 更快，且保证依赖版本锁定）
4. 执行 npx hexo generate 构建静态文件
5. 将 public/ 目录下的所有文件推送到 Pages 仓库的 gh-pages 分支
6. gh-pages 分支的历史会被覆盖（保持只存最新版本）

6.5 提交并推送

git add .github/git commit -m "ci: add GitHub Actions deploy workflow"git push origin main

推送后，打开源码仓库的 Actions 标签页，可以看到工作流正在执行。等待黄色的运行中图标变为绿色勾号，说明部署成功。

七、配置 GitHub Pages

7.1 启用 Pages 服务

1. 打开 Pages 仓库 → Settings → Pages
2. Source 选择 Deploy from a branch
3. Branch 选择 gh-pages，目录选 / (root)
4. 点击 Save

配置完成后，博客即可通过 https://你的用户名.github.io/你的Pages仓库名/ 访问。

7.2 配置自定义域名

绑定自己的域名可以让博客更专业。以下以 blog.example.com 为例：

第一步：在域名 DNS 管理后台添加解析记录

第二步：在 Pages 仓库设置域名

在 Pages 仓库的 Settings → Pages → Custom domain 中输入 blog.example.com，点击 Save。GitHub 会自动签发 SSL/TLS 证书。

第三步：在源码仓库添加 CNAME 文件

在 source/ 目录下创建 CNAME 文件（无扩展名），内容为你的域名：

blog.example.com

为什么 CNAME 文件要放在 source/ 目录？ 因为 hexo generate 时，source/ 下的所有文件（不含 _posts/ 中的文章）会原样复制到 public/，确保每次构建后 CNAME 文件都在部署目录中。

八、日常写作工作流

所有配置完成后，日常使用就变得非常简单：

# 1. 创建新文章hexo new post "新文章标题"# 2. 用任何编辑器编辑 Markdown 文件#    文件位置：source/_posts/新文章标题.mdcode source/_posts/新文章标题.md# 3. 本地预览（可选，但推荐）hexo clean && hexo generate && hexo server# 浏览器访问 http://localhost:4000# 4. 提交并推送git add source/_posts/git commit -m "post: add 新文章标题"git push

推送后等待 1-2 分钟，GitHub Actions 构建部署完成，博客即自动更新。

九、最佳实践与注意事项

9.1 .gitignore 配置

node_modules/public/.deploy_git/db.json*.log.DS_Store

确保 node_modules/ 和 public/ 不提交到 Git 仓库。

9.2 借助 CDN 加速静态资源

国内访问 GitHub Pages 速度较慢，可以使用 jsDelivr CDN 对主题的静态资源进行加速。

以本博客的配置为例，在 _config.yml 中添加 CDN 配置：

cdn:  enable: true  url: 'https://cdn.jsdelivr.net/gh/你的用户名/你的源码仓库@main/source'  vendors:    highlight_js: 'https://cdn.jsdelivr.net/npm/highlight.js@11.10.0'    highlight_css: 'https://cdn.jsdelivr.net/npm/highlight.js@11.10.0/styles/atom-one-dark.min.css'

jsDelivr 的 GitHub 加速格式：https://cdn.jsdelivr.net/gh/{用户名}/{仓库}@{分支}/{文件路径}，完全免费，无需注册。

9.3 为文章添加封面图

在文章 YAML 头部添加 cover 字段可以设置封面图，在首页和文章列表中以卡片形式展示。推荐使用图床存储图片，避免图片文件占用源码仓库空间。

---title: 文章标题cover: https://图床域名/path/to/cover.jpg---

9.4 插件推荐

9.5 常见问题排查

Q1：GitHub Actions 构建失败

# 查看 Actions 日志中的具体错误

常见原因：

• HEXO_DEPLOY Secret 未配置或 Token 已过期 → 检查 Secrets 设置
• PUBLISH_REPOSITORY 格式错误 → 必须为 用户名/仓库名
• Token 缺少 repo 权限 → 重新生成 Token 时确认勾选 repo

Q2：博客更新但页面未变化

1. GitHub Pages 部署通常有 1-2 分钟延迟
2. 尝试强制刷新浏览器（Cmd+Shift+R / Ctrl+F5）
3. 确认 GitHub Actions 工作流运行成功（绿色勾号）

Q3：自定义域名 SSL 证书未生效

• GitHub Pages 的 SSL 证书通过 Let’s Encrypt 自动签发，首次配置可能需要等待 5-15 分钟
• 确认 DNS 的 CNAME 记录已正确指向 你的用户名.github.io
• 可以在 Pages 设置页面取消绑定再重新绑定，触发证书重新签发

Q4：图片加载失败

• 确认图片 URL 可公开访问
• 使用图床（如 SM.MS、Cloudflare R2、阿里云 OSS）存储图片
• 或使用 jsDelivr 加速 GitHub 仓库中的图片：https://cdn.jsdelivr.net/gh/用户名/仓库@分支/图片路径

参考资料

• Hexo 官方文档
• GitHub Pages 官方文档
• GitHub Actions 官方文档
• hexo-deploy-github-pages-action
• hexo-abbrlink 插件
• Keep 主题文档
• Butterfly 主题文档
• jsDelivr CDN 文档
• 本博客 GitHub Actions 工作流源码

适用环境：macOS（Intel / Apple Silicon）+ Homebrew + zsh
目标：在无法直接访问 Anthropic 官方服务的环境下，让 Claude Code 通过国内大模型（DeepSeek、Kimi、GLM、MiniMax 等）正常运行。

一、安装 Claude Code

Claude Code 是 Anthropic 推出的终端 AI 编程助手，可通过 Homebrew 一键安装：

brew install --cask claude-code@latest

安装完成后，终端输入：

claude

如果看到 Claude Code 的 ASCII 艺术启动画面，说明安装成功。

二、国内网络环境下的核心问题

安装完成后，直接运行 claude 大概率会报错：

Unable to connect to Anthropic servicesFailed to connect to api.anthropic.com: ERR_BAD_REQUEST

原因：Claude Code 默认直连 Anthropic 官方 API（api.anthropic.com），而国内网络环境无法稳定访问该地址。

解决思路：Claude Code 底层调用的是 Anthropic Messages API。国内大模型厂商（DeepSeek、Kimi、GLM、MiniMax 等）已经提供了兼容该协议的接口。我们只需修改几个环境变量，让 Claude Code 把请求转发到国内模型即可。

三、方案探索：ccswitch 工具（及踩坑记录）

社区有一个专门用于 Claude Code 模型切换的开源工具 claude-code-switch（简称 ccswitch），理论上可以一键切换模型。

3.1 尝试安装 ccswitch

npm install -g claude-code-switch

踩坑 1：权限报错（EACCES）

npm error code EACCESnpm error syscall symlinknpm error path ../lib/node_modules/claude-code-switch/bin/ccs.jsnpm error dest /usr/local/bin/ccs

原因：macOS 的 /usr/local/bin 默认需要 root 权限写入，npm -g 全局安装时无法创建符号链接。

⚠️ 不建议使用 sudo npm install -g。npm 包的 postinstall 脚本会以 root 权限执行任意代码，存在供应链攻击风险。更安全的做法是将全局包安装到用户目录，或直接使用 npx。

3.2 改用 npx 运行（无需安装）

npx claude-code-switch deepseek

踩坑 2：切换后无输出 / 环境变量未生效

npx claude-code-switch status# （没有任何输出）echo $ANTHROPIC_BASE_URL# （空）

原因：~/.ccswitch/models.json 配置文件不存在，ccswitch 找不到 API Key，导致切换命令实际上没有生效。

3.3 创建 ccswitch 配置文件

mkdir -p ~/.ccswitchcat > ~/.ccswitch/models.json << 'EOF'{  "deepseek": {    "base_url": "https://api.deepseek.com/anthropic",    "api_key": "sk-你的DeepSeekKey",    "model": "deepseek-chat"  },  "kimi": {    "base_url": "https://api.moonshot.cn/anthropic",    "api_key": "sk-你的KimiKey",    "model": "kimi-k2-thinking-turbo"  }}EOF

踩坑 3：填好 Key 后仍然无效

即使配置文件存在且 Key 正确，npx claude-code-switch deepseek 执行后仍然没有任何反馈，echo $ANTHROPIC_BASE_URL 依然为空。

结论：ccswitch 工具在当前版本（0.0.7）下存在稳定性问题，不建议作为主要生产工具。我们转而使用更直接、更可靠的手动环境变量配置方案。

四、最终推荐方案：手动配置环境变量

这是最透明、最稳定的方式，没有中间工具，出了问题一眼就能看出来。

4.1 获取 API Key

注册后进入「API Keys」页面，创建并复制 Key。

4.2 在当前终端手动设置（临时生效）

把 sk-你的DeepSeekKey 替换为真实 Key，在当前终端执行：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeekKey"export ANTHROPIC_MODEL="deepseek-chat"

验证是否生效：

echo $ANTHROPIC_BASE_URL# 输出：https://api.deepseek.com/anthropic

启动 Claude Code：

claude

如果左下角显示 deepseek-v4-pro（或类似的 DeepSeek 模型标识），说明配置成功。

五、长期化配置：写入 ~/.zshrc

上面的 export 只对当前终端窗口有效，关闭后失效。为了方便长期使用，我们将配置写入 ~/.zshrc。

5.1 编辑 ~/.zshrc

open -e ~/.zshrc# 或者使用 VS Code：code ~/.zshrc

在文件末尾追加以下内容（务必将 sk-... 替换为你的真实 API Key）：

# ============================================# Claude Code 国内大模型切换配置# ============================================# DeepSeek 配置cc-ds() {  export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"  export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeekKey"  export ANTHROPIC_MODEL="deepseek-chat"  echo "✅ 已切换至 DeepSeek"}# Kimi 配置cc-kimi() {  export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"  export ANTHROPIC_AUTH_TOKEN="sk-你的KimiKey"  export ANTHROPIC_MODEL="kimi-k2-thinking-turbo"  echo "✅ 已切换至 Kimi"}# GLM 配置（可选）cc-glm() {  export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"  export ANTHROPIC_AUTH_TOKEN="sk-你的GLMKey"  export ANTHROPIC_MODEL="glm-4-7"  echo "✅ 已切换至 GLM"}# 恢复官方 Claudecc-official() {  unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL  echo "✅ 已恢复官方 Claude"}# 快捷启动命令ccd() { cc-ds; claude "$@"; }cck() { cc-kimi; claude "$@"; }ccg() { cc-glm; claude "$@"; }

5.2 重新加载配置

source ~/.zshrc

六、日常使用速查表

配置完成后，以下是常用的快捷命令：

6.1 验证当前使用的模型

在 Claude Code 运行界面，左下角会显示当前模型名称，例如：

deepseek-v4-pro · API Usage Billing

或者在终端执行：

echo $ANTHROPIC_MODEL

七、主流模型配置参数速查

八、常见问题

Q1：Claude Code 启动后仍然显示 “Unable to connect to Anthropic services”

排查步骤：

1. 检查环境变量是否生效：echo $ANTHROPIC_BASE_URL
2. 如果为空，说明当前终端没有正确加载配置，重新执行 source ~/.zshrc
3. 检查 API Key 是否正确（Key 错误会导致认证失败）
4. 检查网络是否能访问对应平台（如 curl https://api.deepseek.com）

Q2：新开的终端窗口需要重新设置环境变量吗？

答：如果已经按照第五节写入了 ~/.zshrc，并且执行过 source ~/.zshrc，则新终端会自动继承配置。但环境变量不会自动切换模型，需要手动执行 cc-ds 或直接使用 ccd 启动。

Q3：如何让 Claude Code 默认使用国内模型，而不是每次手动切换？

答：在 ~/.zshrc 中直接写入 export 语句（而不是函数），这样每次打开终端就自动生效：

# 默认使用 DeepSeekexport ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeekKey"export ANTHROPIC_MODEL="deepseek-chat"

Q4：API 调用费用如何？

答：各平台都有免费额度，DeepSeek 和 GLM 的免费额度相对 generous。具体费率请查看各平台的官方定价页面。Claude Code 作为编程助手，代码补全和文件操作的 Token 消耗量通常不大。

八、Claude Code 入门：常用命令与实战案例

配置好模型只是第一步，下面介绍 Claude Code 的核心用法，帮助你快速上手这个终端 AI 编程助手。

8.1 启动方式

Claude Code 有两种启动方式：

最佳实践：进入你的项目目录后再启动 Claude Code，这样它能自动识别项目结构、技术栈和依赖关系。

cd ~/my-projectccd  # 或 cck，取决于你配置的快捷命令

8.2 内置命令（以 / 开头）

在 Claude Code 交互界面中，输入 ? 可查看所有快捷命令。以下是核心命令：

使用示例

> /reviewClaude 会分析你当前打开的文件，指出：- 潜在的逻辑错误- 性能优化建议- 代码风格问题- 安全风险

8.3 日常交互模式

Claude Code 的核心使用方式是自然语言对话。你可以像和同事交流一样描述需求。

场景 1：代码生成

> 帮我写一个 Python 函数，读取 CSV 文件并返回按日期排序的 DataFrameClaude 会：1. 询问 CSV 的日期列名（或根据上下文推断）2. 生成带类型注解和文档字符串的函数3. 询问是否需要处理异常（如文件不存在、日期格式错误）4. 将代码写入你指定的文件

场景 2：代码重构

> 把 src/utils.py 里的重复逻辑提取成独立函数Claude 会：1. 读取 src/utils.py2. 识别重复代码块3. 提出重构方案（展示 diff）4. 经你确认后执行修改

场景 3：Debug 调试

> 运行项目测试时报错了，帮我看看Claude 会：1. 执行测试命令（如 pytest / npm test）2. 分析错误堆栈3. 定位问题根源4. 提出修复方案或自动修复

场景 4：批量文件操作

> 把所有 .js 文件里的 console.log 替换成 logger.debugClaude 会：1. 搜索项目中的所有 .js 文件2. 展示将要修改的文件列表3. 经确认后执行批量替换4. 生成变更摘要

8.4 文件与代码操作

Claude Code 可以直接操作文件系统，所有修改都会征求你的确认。

读取文件

> 看一下 src/App.tsx 的内容> 比较 src/old.js 和 src/new.js 的区别> 搜索项目中所有用到 useEffect 的地方

创建文件

> 创建一个 Dockerfile，基于 Node 18 镜像，暴露 3000 端口> 在 tests/ 目录下添加 login.spec.js 的 Playwright 测试

编辑文件

> 在 README.md 的安装章节后面添加 Troubleshooting 部分> 给 src/api.js 里的 fetchUser 函数添加重试逻辑> 删除 src/components/OldComponent.jsx（已废弃）

运行终端命令

Claude Code 可以代表你运行终端命令，执行前会请求确认：

> 安装 axios 和 lodashClaude: 我将运行 `npm install axios lodash`，是否继续？ (Y/n)> 把当前分支推送到远程Claude: 我将运行 `git push origin feature-branch`，是否继续？ (Y/n)

8.5 项目初始化：CLAUDE.md

/init 命令会在项目根目录创建一个 CLAUDE.md 文件，这是给 Claude 的"项目说明书"。

CLAUDE.md 的作用：

• 描述项目架构和技术栈
• 定义编码规范（缩进、命名约定、注释风格）
• 指定测试策略和目录结构
• 列出需要特别注意的业务逻辑

示例 CLAUDE.md：

# 项目规范## 技术栈- React 18 + TypeScript- Vite 构建工具- Tailwind CSS- React Query 管理服务端状态## 编码规范- 使用函数组件 + Hooks- 类型定义放在 `src/types/` 目录- API 请求统一封装在 `src/api/` 目录- 组件 props 必须写接口定义## 测试要求- 新增功能必须配套单元测试- 使用 Vitest + React Testing Library- 测试文件放在 `__tests__/` 目录或 `.test.ts` 后缀

创建后，Claude 在后续对话中会自动遵循这些规范，无需每次重复说明。

8.6 实战完整案例

案例：从零搭建一个 Express API 项目

步骤 1：创建项目目录并进入

mkdir my-api && cd my-apiccd

步骤 2：初始化项目

> 初始化一个 Node.js Express 项目，使用 TypeScript，添加 eslint 和 prettier 配置

Claude 会：

1. 运行 npm init -y
2. 安装 express、typescript、@types/express、eslint、prettier 等依赖
3. 创建 tsconfig.json
4. 创建 .eslintrc.js 和 .prettierrc
5. 创建 src/index.ts 入口文件

步骤 3：创建用户模块

> 创建用户相关的 CRUD API，包括：> - GET /users 获取用户列表> - GET /users/:id 获取单个用户> - POST /users 创建用户> - PUT /users/:id 更新用户> - DELETE /users/:id 删除用户> > 使用内存数组存储数据即可，先不做数据库

Claude 会：

1. 创建 src/routes/users.ts
2. 创建 src/types/user.ts 定义 User 接口
3. 在 src/index.ts 中注册路由
4. 添加基本的输入验证

步骤 4：添加测试

> 给用户模块添加 Jest 单元测试，覆盖所有路由

Claude 会：

1. 安装 jest、supertest、@types/jest
2. 创建 src/routes/users.test.ts
3. 配置 jest.config.js

步骤 5：代码审查

> /review

Claude 会检查代码中的潜在问题，比如：

• 缺少错误处理中间件
• 没有输入校验
• TypeScript 类型不够严谨

步骤 6：提交代码

> /commit

Claude 会自动：

1. git add .
2. 生成规范的 commit message（如 feat: add user CRUD endpoints with tests）
3. git commit

8.7 快捷键与效率技巧

效率技巧

1. 多轮对话保持上下文：Claude Code 会记住整个会话的历史，你可以随时说"刚才那个函数再改一下"或"回到上一步"。

2. @ 引用文件：在对话中用 @文件名 快速让 Claude 关注特定文件。

   > @src/utils.js 里的 parseDate 函数有 bug，帮我修复

3. 批量确认：Claude 在执行危险操作（如删除文件、git push）前会征求确认。你可以输入 Y 确认单条，A 确认全部剩余操作，N 跳过，Q 退出。

4. 查看成本：随时输入 /cost 了解当前会话消耗了多少 Token，便于控制预算。

5. 结合 tmux/screen：在 tmux 会话中运行 Claude Code，即使关闭终端也不会中断长任务。

8.8 使用注意事项

九、Skills 系统详解：扩展 Claude Code 的能力边界

Claude Code 的 Skills 系统是其最强大的特性之一。通过 Skills，你可以为 Claude 注入特定领域的知识、编码规范、团队约定，甚至自定义命令。本节将详细讲解 Skills 的安装、作用范围，以及国内网络环境下的最佳实践。

9.1 Skills 是什么

简单来说，Skill 是一个包含 SKILL.md 文件的文件夹，里面写满了给 Claude 的「专项 Instructions」。安装后，Claude 在对应场景下会自动调用这些知识。

类比理解：

• 如果把 Claude Code 比作一个通用程序员
• 那么 Skills 就是他的「专业资格证书」——装上 React Skill，他就是一个熟手 React 开发者；装上 Testing Skill，他就精通各种测试框架

典型使用场景：

• 团队编码规范（缩进、命名、注释风格）
• 特定技术栈的深度知识（Next.js、Django、Rust 等）
• 内部工具链的使用方法（私有 npm 仓库、内部 CLI）
• 代码审查标准（安全规范、性能要求）

9.2 Skills 的两种作用范围

这是最容易混淆的地方。Claude Code 的 Skills 同时支持全局和项目级两种作用范围，优先级规则是：项目级 > 全局。

全局 Skills（用户级）

示例：你个人习惯使用 2 空格缩进、单引号、尾部逗号，可以把这些偏好写入一个全局 Skill，这样每个项目都会自动遵循。

项目级 Skills（局部，默认）

示例：公司 A 项目使用 Vue + Pinia + Element Plus，有一套特定的组件封装规范。把这些写入项目级 Skill，提交到 Git 仓库，团队所有人都能获得一致的 AI 辅助体验。

优先级规则

当全局和项目级存在同名 Skill 时，项目级优先。这意味着：

• 你可以有一个全局的「通用代码规范」Skill
• 同时在某个项目中放置「该项目特定的规范」Skill
• Claude 会优先遵循项目级的约定

9.3 安装 Skills 的两种方式

方式一：插件市场安装（推荐，网络通畅时）

Claude Code 内置了插件市场体系，类似于 npm 的包管理。

核心命令：

# 查看已添加的市场/plugin marketplace list# 添加市场（必须使用 HTTPS 地址）/plugin marketplace add https://github.com/anthropics/claude-plugins-official# 浏览市场可用插件/plugin marketplace list# 安装插件（格式：插件名@市场名）/plugin install code-review@claude-plugins-official# 查看已安装插件/plugin list# 启用/禁用插件/plugin enable 插件名@市场名/plugin disable 插件名@市场名# 卸载插件/plugin uninstall 插件名@市场名

⚠️ 重要注意：/plugin install 默认安装到项目级（./.claude/skills/），不是全局的。这意味着：

• 你在项目 A 安装了 Skill
• 进入项目 B 后，该 Skill 不可用

如果你想让所有项目都能用，安装后需要手动复制到全局目录：

# 从项目级复制到全局（macOS/Linux）cp -r ./.claude/skills/skill-name ~/.claude/skills/

方式二：本地手动安装（离线环境、国内网络受限时）

如果网络不畅或处于离线环境，可以直接将 Skill 文件夹复制到指定目录。

步骤 1：获取 Skill 文件

从 GitHub 下载 Skill 仓库的 ZIP 包，解压后得到 Skill 文件夹（内部应包含 SKILL.md 文件）。

步骤 2：复制到目标目录

# 全局安装（所有项目可用）cp -r /path/to/skill-folder ~/.claude/skills/# 项目级安装（仅当前项目可用）mkdir -p ./.claude/skillscp -r /path/to/skill-folder ./.claude/skills/

步骤 3：验证安装

重启 Claude Code，然后询问：

> 你有哪些可用的 Skills？

如果 Claude 列出了你刚安装的 Skill，说明安装成功。

9.4 国内网络环境下的 Skills 安装策略

国内用户安装 Skills 时，最常见的问题是访问 GitHub 慢或超时。以下是几种经过验证的解决方案：

策略 1：配置 Git 代理（推荐）

如果你已经有代理工具（Clash、Surge、V2Ray 等），配置 Git 走代理：

# HTTP 代理git config --global http.proxy http://127.0.0.1:7890git config --global https.proxy http://127.0.0.1:7890# SOCKS5 代理（部分工具使用）git config --global http.proxy socks5://127.0.0.1:7890

端口号 7890 请替换为你实际代理工具的 HTTP/SOCKS5 端口（Clash 默认 7890，Surge 默认 6152）。

配置后，/plugin marketplace add 和 /plugin install 命令就可以正常访问 GitHub 了。

策略 2：使用 GitHub 镜像站

如果不想配置代理，可以使用国内的 GitHub 镜像站：

# 添加市场时使用镜像地址/plugin marketplace add https://gh.api.99988866.xyz/https://github.com/anthropics/claude-plugins-official

常用镜像前缀：

• https://gh.api.99988866.xyz/https://github.com/...
• https://mirror.ghproxy.com/https://github.com/...
• https://ghps.cc/https://github.com/...

镜像站稳定性不一，如果某个失效，尝试换一个。

策略 3：完全离线安装（内网/无网络环境）

这是最稳妥的方案，适合公司内网或完全无法访问外网的环境。

步骤 1：在能上网的机器上下载 Skills

访问 Claude Code 官方插件仓库或社区仓库，下载 ZIP 包：

• 官方市场：https://github.com/anthropics/claude-plugins-official
• 社区市场：搜索 claude code skills github

步骤 2：传输到目标机器

通过 U 盘、内网文件服务器、企业微信/钉钉等方式，将解压后的 Skill 文件夹传输到目标 macOS 机器。

步骤 3：手动安装

# 创建全局 skills 目录mkdir -p ~/.claude/skills# 复制 Skill 文件夹（假设传输到了 ~/Downloads/skills/）cp -r ~/Downloads/skills/* ~/.claude/skills/# 验证目录结构ls -la ~/.claude/skills/# 应该看到各个 Skill 文件夹，每个文件夹内有 SKILL.md

步骤 4：重启 Claude Code 并使用

ccd

> 你有哪些可用的 Skills？> /skill-name  # 调用特定 Skill

9.5 热门 Skills 推荐

以下是社区中评价较高的 Skills，供参考：

安装方法示例：

/plugin install code-review@claude-plugins-official/plugin install testing@claude-plugins-official

9.6 自定义自己的 Skill

如果现成的 Skills 不能满足需求，你可以自己写一个。

步骤 1：创建 Skill 目录和文件

mkdir -p ~/.claude/skills/my-team-rulescat > ~/.claude/skills/my-team-rules/SKILL.md << 'EOF'# My Team Coding Rules## 命名规范- 变量/函数：camelCase- 组件/类：PascalCase- 常量：UPPER_SNAKE_CASE- 私有属性：_前缀## 代码风格- 缩进：2 个空格- 引号：单引号- 分号：必须- 行尾逗号：多行时必须## 文件组织- 组件放在 `src/components/`- 工具函数放在 `src/utils/`- API 封装放在 `src/api/`- 类型定义放在 `src/types/`## 提交规范- feat: 新功能- fix: 修复- docs: 文档- style: 格式- refactor: 重构- test: 测试- chore: 构建/工具EOF

步骤 2：重启 Claude Code 即可生效

现在当你让 Claude 写代码时，他会自动遵循你定义的规范。

9.7 Skills 使用注意事项

写在最后

Claude Code 的核心价值在于把 AI 能力无缝嵌入到终端工作流中。它不是一个简单的聊天机器人，而是能读懂你的代码、操作你的文件系统、运行你的测试、提交你的代码的"编程搭档"。

通过 Skills 系统，你可以进一步定制这个搭档的专业能力——无论是团队的编码规范、特定技术栈的深度知识，还是个人的开发偏好，都能通过 Skills 注入到 Claude 中，让它真正成为"懂你的 AI"。

配合 DeepSeek 或 Kimi 等国内模型，即使在不方便访问 Anthropic 官方服务的环境下，你也能获得流畅且高度个性化的 AI 编程体验。

建议从一个小功能或一次代码重构开始尝试，逐步熟悉它的交互模式。你会发现，很多原本需要查文档、写样板代码、反复调试的工作，现在只需几句话就能完成。

祝你编码愉快！

十、总结

本文记录了在 macOS 上安装和配置 Claude Code 的完整过程，重点解决了国内网络环境下无法连接 Anthropic 官方服务的问题。

核心要点：

• Claude Code 通过 Anthropic Messages API 通信，国内模型提供了兼容接口
• 修改 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL 三个环境变量即可切换
• ccswitch 工具目前不够稳定，推荐直接手动配置 + 写入 ~/.zshrc
• 使用 npx 或用户级 npm 全局目录，避免 sudo npm install -g 的安全风险

现在，输入 ccd 或 cck，开始你的 AI 编程之旅吧。

参考链接

• Claude Code 官方文档：https://docs.anthropic.com/en/docs/claude-code/overview
• DeepSeek API 平台：https://platform.deepseek.com
• Kimi API 平台：https://platform.moonshot.cn
• ccswitch 项目：https://github.com/yourccswitch/claude-code-switch