Chen’Blog

Claude Code常用MCP、Skill

Mon, 18 May 2026 16:42:26 +0800

Claude Code 常用 MCP、Skill 全指南

🎯 你的全栈开发工作流

作为一名全栈开发工程师，你的工作流可以拆分为 5 个阶段：

原型图设计 → 前后端代码编写 → 部署上线 → AI浏览器排查问题 → 文档输出

Claude Code 的扩展生态（MCP、Skill、LSP、Hook）可以在这 5 个阶段的每一个环节提供自动化辅助。本文整理了 59 个常用插件，按你的工作流阶段进行筛选和匹配，标注了每个插件的相关性等级，并包含详细的用途介绍、安装命令、官网地址和 CC Switch 配置方式。

💡 相关性等级说明：★ 核心必备（6 个）→ ☆ 强烈推荐（13 个）→ △ 按需选择（40 个）

📊 工作流 × 插件匹配全览

下表帮你快速判断每个插件在工作流中的位置和重要性：

插件名	类型	适用阶段	相关性
Context7	MCP	前后端编码	★ 核心
Sequential Thinking	MCP	全局（推理分析）	★ 核心
Playwright	MCP	排查问题 + 测试	★ 核心
Frontend Design	Skill	原型设计 + 前端	★ 核心
Feature Dev	Skill	前后端编码 + 文档	★ 核心
Planning with Files	Skill	全局（任务管理）+ 文档	★ 核心
Figma	MCP+Skill	原型设计	☆ 推荐
GitHub	MCP	前后端编码	☆ 推荐
Serena	MCP	前后端编码	☆ 推荐
Superpowers	Skill	前后端编码	☆ 推荐
PR Review Toolkit	Skill+Agent	前后端编码（评审）	☆ 推荐
Semgrep	MCP+Skill+Hook	前后端编码（安全）	☆ 推荐
Sentry	MCP+Skill	排查问题 + 监控	☆ 推荐
Vercel	Skill	部署上线	☆ 推荐
Code Review	Skill	前后端编码（评审）	☆ 推荐
Commit Commands	Skill	前后端编码（Git）	☆ 推荐
Security Guidance	Hook	前后端编码（安全）	☆ 推荐
Ralph Loop	Skill+Hook	前后端编码（迭代）	☆ 推荐
Hookify	Skill+Agent+Hook	全局（自动化）	☆ 推荐
Postman	MCP+Skill+Agent	后端（API开发）	△ 按技术栈
Supabase	MCP	后端（数据库）+ 部署	△ 按技术栈
Firebase	MCP	后端 + 部署	△ 按技术栈
Pinecone	MCP+Skill	后端（向量数据库）	△ 按技术栈
Stripe	MCP+Skill	后端（支付）	△ 按技术栈
Laravel Boost	MCP	后端（Laravel）	△ 按技术栈
HuggingFace	MCP+Skill	后端（AI模型集成）	△ 按技术栈
Greptile	MCP	前后端编码（代码搜索）	△ 按技术栈
Firecrawl	Skill	前后端编码（数据抓取）	△ 按技术栈
Qodo Skills	Skill	前后端编码（质量/测试）	△ 按技术栈
Coderabbit	Skill+Agent	前后端编码（评审）	△ 按技术栈
PostHog	MCP+Skill+Agent	排查问题（产品分析）	△ 按技术栈
PagerDuty	MCP+Skill	部署上线（风险评分）	△ 按技术栈
Sonatype Guide	MCP	前后端编码（依赖安全）	△ 按技术栈
Agent SDK Dev	Skill+Agent	特定（Agent SDK开发）	△ 特定场景
Plugin Dev	Skill+Agent	特定（插件开发）	△ 特定场景
Skill Creator	Skill	特定（Skill开发）	△ 特定场景
Code Simplifier	Agent	前后端编码（重构）	△ 按需
Playground	Skill	原型设计（HTML演示）	△ 按需
Claude Code Setup	Skill	全局（初始化配置）	△ 按需
Claude MD Management	Skill	全局（配置维护）	△ 按需
Explanatory Output Style	Hook	全局（学习/教学）	△ 按需
Learning Output Style	Hook	全局（学习/教学）	△ 按需
Linear	MCP	全局（项目管理）	△ 按团队工具
Atlassian	MCP+Skill	全局（项目管理）	△ 按团队工具
Asana	MCP	全局（项目管理）	△ 按团队工具
Notion	MCP+Skill	全局（文档协作）	△ 按团队工具
Slack	MCP+Skill	全局（沟通协作）	△ 按团队工具
GitLab	MCP	全局（代码托管）	△ 按团队工具
Circleback	MCP	全局（会议/邮件）	△ 按团队工具
TypeScript LSP	LSP	前后端编码	△ 按语言
Pyright LSP	LSP	后端（Python）	△ 按语言
Gopls LSP	LSP	后端（Go）	△ 按语言
Rust Analyzer LSP	LSP	后端（Rust）	△ 按语言
ClangD LSP	LSP	前后端（C/C++）	△ 按语言
PHP LSP	LSP	后端（PHP）	△ 按语言
Swift LSP	LSP	原生（Swift）	△ 按语言
Kotlin LSP	LSP	原生（Kotlin）	△ 按语言
C# LSP	LSP	后端（C#）	△ 按语言
JDTLS LSP	LSP	后端（Java）	△ 按语言
Lua LSP	LSP	特定（Lua）	△ 按语言
Ruby LSP	LSP	后端（Ruby）	△ 按语言

💡 综上，我的核心建议是：优先装 6 个核心（★），再按你的技术栈从推荐（☆）和按需（△）中选配。不必全装——每个插件都会消耗上下文窗口和启动时间，保持 2-3 个 MCP + 3-5 个 Skill 活跃即可。

⭐ 核心必备（6 个 — 建议最先安装）

★ 1. Context7 — 实时最新框架文档

类型：MCP
提供方：第三方（Upstash 开源）
适用阶段：前后端编码
用途：根据你项目中实际安装的框架和库版本，自动拉取版本匹配的最新官方文档并注入对话上下文。当你使用 React 19、Next.js 15、Prisma 6 等大版本更新频繁的框架时，Context7 确保 Claude 给出的是对的 API、对的参数、对的用法，而不是基于过时训练数据的幻觉代码。

✅ 推荐理由：API 幻觉是 AI 编程最大的坑之一。Context7 直接解决了”你训练数据里的 API 已经废弃了”这个问题。

# Claude Code 安装
claude mcp add --scope user \
  --header "CONTEXT7_API_KEY: YOUR_API_KEY" \
  --transport http \
  context7 https://mcp.context7.com/mcp

CC Switch 安装：MCP 页签 → 添加 → 类型选 HTTP → URL 填 https://mcp.context7.com/mcp → Headers 添加 CONTEXT7_API_KEY: 你的Key
🔗 官网：https://context7.com

★ 2. Sequential Thinking — 结构化分步推理

类型：MCP
提供方：Anthropic 官方（Model Context Protocol 项目）
适用阶段：全局（架构设计、Bug分析、复杂算法都需要）
用途：为 Claude 提供结构化的分步推理框架。当你面对复杂问题时（比如设计架构、分析深层 Bug、优化算法），它让 Claude 像人类专家一样”一步一步想”——支持思维分叉探索不同方向、回溯修正之前的错误判断、动态调整思考深度。显著减少复杂场景下的逻辑跳跃和结论错误。

💡 适用场景：架构选型、Bug 根因分析、算法优化、多方案对比——凡是需要”想清楚再做”的任务都应该开它。

# Claude Code 安装
claude mcp add sequential-thinking -s user \
  -- npx -y @modelcontextprotocol/server-sequential-thinking

CC Switch 安装：MCP 页签 → 添加 → 类型选 stdio → 命令 npx → 参数 -y @modelcontextprotocol/server-sequential-thinking
🔗 官网：https://github.com/modelcontextprotocol/servers

★ 3. Playwright — 浏览器自动化测试与UI排查

类型：MCP
提供方：第三方（Microsoft）
适用阶段：排查问题 + 测试（你的第4阶段核心工具）
用途：让 Claude 直接操控真实浏览器——导航页面、点击按钮、填写表单、截图对比、抓取网络请求、检查控制台错误。在你”AI控制浏览器排查开发期间的问题”这个阶段，Playwright 就是你的手和眼睛；开发期可以自动验证 UI 是否正确渲染，调试期可以复现 Bug 场景，测试期可以执行端到端测试。

✅ 推荐理由：你的工作流第 4 阶段（AI浏览器排查问题）的核心工具。不用再手动开 DevTools 了。

# Claude Code 安装
claude mcp add playwright -- npx -y @anthropic-ai/playwright-mcp

CC Switch 安装：MCP 页签 → 添加 → 类型选 stdio → 命令 npx → 参数 -y @anthropic-ai/playwright-mcp
🔗 官网：https://playwright.dev

★ 4. Frontend Design — 生产级前端UI生成

类型：Skill
提供方：Anthropic 官方（52.7K+ 安装量）
适用阶段：原型设计 + 前端编码
用途：专门用于生成有独特设计感、可直接投产的前端界面。不同于普通 AI 生成的千篇一律的 UI（”AI 味审美”），它会根据项目的用途定位、目标用户、品牌基调、设计约束来生成差异化的界面代码。内置 67 种 UI 风格预设和 100 条设计推理规则——当你告诉它”做一个面向中国茶饮品牌的会员小程序”，它会生成有东方美学调性的设计，而非泛泛的蓝色按钮+白色背景。

💡 适用场景：快速出原型、需要设计感的页面、避免”AI slop”风格的 UI。

# Claude Code 安装
/plugin install frontend-design@claude-plugins-official

CC Switch 安装：Skills 页签 → 搜索 frontend-design → 一键安装
🔗 官网：https://github.com/anthropics/frontend-design

★ 5. Feature Dev — 7阶段功能开发全流程

类型：Skill + Agent
提供方：Anthropic 官方（89K+ 安装量）
适用阶段：前后端编码 + 文档输出
用途：把”从想法到可交付代码”的整个流程标准化为 7 个阶段：需求探索 → 技术选型 → 架构设计 → 代码实现 → 测试编写 → 代码评审 → 文档生成。对于全栈开发来说，这意味着你不必在每一步都手动写 prompt 告诉 Claude 该做什么——Feature Dev 内置了每个阶段的检查清单和最佳实践，Claude 会自动按流程推进，并把每个阶段的产出物（架构图、接口文档、测试报告）保存下来。

✅ 推荐理由：89K+ 安装量的爆款 Skill，把你的工作流第 2-5 阶段全部覆盖了。

# Claude Code 安装
/plugin install feature-dev@claude-plugins-official

CC Switch 安装：Skills 页签 → 搜索 feature-dev → 一键安装
🔗 官网：https://github.com/anthropics/feature-dev

★ 6. Planning with Files — 跨会话持久化任务规划

类型：Skill
提供方：第三方（OthmanAdi，20K+ GitHub Stars）
适用阶段：全局任务管理 + 文档输出（你的第5阶段）
用途：实现 Manus 风格的持久化工作规划——自动维护 3 个 Markdown 文件：task_plan.md（目标与任务清单）、findings.md（研究发现与调研笔记）、progress.md（操作日志与遇到的错误）。这个插件的核心价值是解决了长任务上下文丢失的问题：当 Claude Code 的上下文窗口满了触发 compaction 后，它可以从这 3 个文件中恢复之前的工作状态，不用从头开始。特别适合需要跨多个会话完成的复杂全栈项目。

⚠️ 重要：长任务（跨多会话）必备。如果你经常遇到”Claude 忘了之前做了什么”的情况，装它。支持中文版 planning-with-files-zh。

# Claude Code 安装
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g

# 或通过市场
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

CC Switch 安装：Skills 页签 → 搜索 planning-with-files → 一键安装（中文版用 planning-with-files-zh）
🔗 官网：https://github.com/OthmanAdi/planning-with-files

☆ 强烈推荐（13 个 — 装上后效率翻倍）

☆ 7. Figma — 设计稿到代码的桥梁

类型：MCP + Skill
提供方：第三方（Figma 官方）
适用阶段：原型设计（你的第1阶段）
用途：直接读取 Figma 设计文件中的图层结构、颜色 token、字体样式、间距系统、组件属性等信息，让 Claude 生成高度还原设计稿的前端代码。不再是”凭描述猜设计”，而是基于真实的设计数据进行代码生成，打通”设计师出图 → 开发者写代码”的效率瓶颈。

# Claude Code 安装
claude mcp add --transport http figma https://mcp.figma.com/mcp

CC Switch 安装：MCP 页签 → 添加 → 类型选 HTTP → URL 填 https://mcp.figma.com/mcp → 首次使用需 OAuth 认证
🔗 官网：https://www.figma.com

☆ 8. GitHub — 代码仓库全操作

类型：MCP
提供方：第三方（GitHub 官方）
适用阶段：前后端编码
用途：在 Claude Code 中直接操作 GitHub 的几乎所有功能：创建和管理 Issue、提交和审查 Pull Request、搜索代码库、查看 Actions CI/CD 状态、管理分支和保护规则。省去在终端和浏览器之间频繁切换的麻烦，你的代码管理和 AI 编程在同一个界面完成。

# Claude Code 安装
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

CC Switch 安装：MCP 页签 → 添加 → 类型选 HTTP → URL 填 GitHub MCP 端点 → Headers 配置 PAT Token
🔗 官网：https://github.com

☆ 9. Serena — 语义级代码分析与编辑

类型：MCP
提供方：第三方（Oraios AI，2900+ Stars，MIT 开源）
适用阶段：前后端编码
用途：基于 LSP 协议提供 IDE 级别的语义代码理解能力——按符号查找、查找所有引用、替换符号定义、按符号位置插入/删除代码。与传统的关键词搜索不同，Serena 理解代码的语义结构（比如它知道 UserService.create() 是一个类的实例方法、继承了哪个基类、被哪些文件调用）。在大型项目中，Serena 能节省 30 倍以上的 token 消耗（不需要把整个文件读进来找函数），同时还提供 Web 仪表盘和跨会话项目记忆。

⚠️ 前置依赖：需要先安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）

# Claude Code 安装
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project "$(pwd)"

CC Switch 安装：MCP 页签 → 类型选 stdio → 命令 uvx → 按上述参数配置
🔗 官网：https://github.com/oraios/serena

☆ 10. Superpowers — 工程方法论技能包

类型：Skill + Agent + Hook
提供方：第三方（Jesse Vincent/obra，20K+ GitHub Stars）
适用阶段：前后端编码
用途：一套让 AI 遵循严格软件工程方法的技能集合，包含 20+ 个技能：交互式头脑风暴（不直接写代码，先讨论方案优劣）、TDD 驱动开发（先写测试再写实现）、系统化调试（按二分法定位问题而非随机猜测）、计划后执行（先出计划再批量实现）。

💡 核心理念：”让 AI 像有经验的工程师一样工作，而不是像实习生一样随手写代码。”

# Claude Code 安装
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# 常用命令
/superpowers:brainstorm      # 交互式头脑风暴
/superpowers:write-plan      # 编写执行计划
/superpowers:execute-plan    # 按计划执行

CC Switch 安装：Skills 页签 → 搜索 superpowers → 一键安装
🔗 官网：https://github.com/obra/superpowers

☆ 11. PR Review Toolkit — 6维度专业代码评审

类型：Skill + Agent
提供方：Anthropic 官方
适用阶段：前后端编码（代码评审）
用途：内含 6 个专业评审 Agent，每个负责一个维度 —— Comment Analyzer（检查注释和文档质量）、PR Test Analyzer（分析测试覆盖率和用例质量）、Silent Failure Hunter（发现被吞掉的异常和边界情况）、Type Design Analyzer（评估类型定义的完整性和约束）、Code Reviewer（综合代码质量评审）、Code Simplifier（提出简化建议）。支持并行评审（6 个 Agent 同时跑），大幅缩短 PR 等待时间。

# Claude Code 安装
/plugin install pr-review-toolkit@claude-plugins-official

# 使用方式
/pr-review-toolkit:review-pr all parallel   # 全维度并行评审

CC Switch 安装：Skills 页签 → 搜索 pr-review-toolkit → 一键安装（需配套 gh CLI）
🔗 官网：https://github.com/anthropics/claude-plugins-official

☆ 12. Semgrep — 实时安全漏洞扫描

类型：MCP + Skill + Hook
提供方：第三方（Semgrep 官方）
适用阶段：前后端编码（安全）
用途：在 Claude 每次编辑代码后自动触发安全扫描，集成三大引擎 —— SAST（静态代码分析，检测 OWASP Top 10 漏洞、SQL 注入、XSS、命令注入等）、SCA（供应链依赖漏洞检测）、Secrets Detection（密钥和敏感信息泄露检测）。发现问题后自动提示 Claude 重新生成代码直到扫描结果干净。

⚠️ 注意：需要先安装 Semgrep CLI（brew install semgrep 或 pipx install semgrep），然后在 Claude Code 中运行 /setup-semgrep-plugin 完成配置。

# 先安装 Semgrep CLI
brew install semgrep       # macOS
pipx install semgrep       # 跨平台

# 在 Claude Code 中安装插件
/plugin                    # → Discover → 搜索 Semgrep → Install

CC Switch 安装：MCP 页签 → 添加 → 类型选 stdio → 命令 semgrep，或在 Skills 页签搜索安装
🔗 官网：https://semgrep.dev

☆ 13. Sentry — 线上错误监控

类型：MCP + Skill
提供方：第三方（Sentry 官方）
适用阶段：排查问题 + 监控（你的第4阶段）
用途：在 Claude Code 中直接查看 Sentry 的错误报告——堆栈跟踪、错误上下文、影响用户数、首次出现时间。当你在排查线上问题时，不需要切到 Sentry 网页在浏览器和代码之间来回看，Claude 可以直接读取错误详情并结合代码上下文给出修复方案。

# Claude Code 安装
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

CC Switch 安装：MCP 页签 → 添加 → 类型选 HTTP → URL 填 https://mcp.sentry.dev/mcp → 配置 Auth Token
🔗 官网：https://sentry.io

☆ 14. Vercel — 一键部署

类型：Skill
提供方：第三方（Vercel 官方）
适用阶段：部署上线（你的第3阶段）
用途：在 Claude Code 中管理 Vercel 部署全流程——触发构建、查看构建日志、配置环境变量、管理域名和 DNS、查看部署历史。开发完成后不需要离开终端就可以完成部署和验证。同时包含 React/Next.js 最佳实践规则。

# Claude Code 安装
/plugin install vercel-labs/agent-skills

CC Switch 安装：Skills 页签 → 搜索 vercel → 一键安装
🔗 官网：https://vercel.com ｜ GitHub

☆ 15. Code Review — 带评分的自动代码评审

类型：Skill
提供方：Anthropic 官方
适用阶段：前后端编码（评审）
用途：对代码进行多维度量化评分（0-100）——安全性、性能、可维护性、正确性、可读性——并给出每个维度的具体改进建议。

💡 与 PR Review Toolkit 的区别：Code Review 更适合日常开发中”写完一个功能就快速检查一下”的轻量场景；PR Review Toolkit 适合正式的 PR 合并前的全面评审。

# Claude Code 安装
/plugin install code-review@claude-plugins-official

CC Switch 安装：Skills 页签 → 搜索 code-review → 一键安装
🔗 官网：https://github.com/anthropics/claude-plugins-official

☆ 16. Commit Commands — 智能Git工作流

类型：Skill
提供方：Anthropic 官方
适用阶段：前后端编码（Git 操作）
用途：自动生成语义化 commit message、智能分组提交文件、一键推送和创建 PR。遵循 Conventional Commits 规范（feat: / fix: / refactor: / docs: 等前缀），不再需要手动想 commit message 怎么写。

# Claude Code 安装
/plugin install commit-commands@claude-plugins-official

CC Switch 安装：Skills 页签 → 搜索 commit-commands → 一键安装
🔗 官网：https://github.com/anthropics/claude-plugins-official

☆ 17. Security Guidance — 实时安全警告

类型：Hook
提供方：Anthropic 官方
适用阶段：前后端编码（安全）
用途：在 Claude 编辑代码时自动检测潜在的命令注入、XSS 跨站脚本、SQL 注入、路径遍历等安全风险模式，给出即时警告。

💡 与 Semgrep 的区别：Security Guidance 在”代码还在键盘上”的时候就拦截危险操作（预防）；Semgrep 在代码写完后做完整扫描（检测）。两者互补。

# Claude Code 安装
/plugin install security-guidance@claude-plugins-official

CC Switch 安装：Skills 页签 → 搜索 security-guidance → 一键安装（Hook 类型）
🔗 官网：https://github.com/anthropics/claude-plugins-official

☆ 18. Ralph Loop — 迭代改进循环

类型：Skill + Hook
提供方：Anthropic 官方
适用阶段：前后端编码（迭代开发）
用途：让 Claude 循环执行同一个任务直到满足完成标准。灵感来自《辛普森一家》的 Ralph Wiggum 角色——“屡败屡战”的精神。适合有明确验证标准的迭代型任务，比如”修复所有 TypeScript 类型错误”或”让所有单元测试通过”。

# Claude Code 安装
/plugin install ralph-loop@claude-plugins-official

# 使用方式
/ralph-loop "你的任务描述" --max-iterations 20 --completion-promise "DONE"

CC Switch 安装：Skills 页签 → 搜索 ralph-loop → 一键安装
🔗 官网：https://github.com/anthropics/claude-code

☆ 19. Hookify — 自动生成自定义Hook

类型：Skill + Agent + Hook
提供方：Anthropic 官方
适用阶段：全局自动化
用途：分析你与 Claude 的交互模式，自动生成自动化 Hook。比如你总是让 Claude 在编辑完文件后运行 npx prettier --write，Hookify 会发现这个模式并生成一个 PostToolUse Hook，从此自动化执行。把”我每次都重复说的那句话”变成”系统自动遵守的规则”。

# Claude Code 安装
/plugin install hookify@claude-plugins-official

CC Switch 安装：Skills 页签 → 搜索 hookify → 一键安装
🔗 官网：https://github.com/anthropics/claude-plugins-official

🔧 按你的技术栈选择

以下是和你的技术栈强相关的插件——不需要全装，按你实际使用的技术选配。

🗄️ 后端技术栈

△ Postman — API全生命周期管理

类型：MCP + Skill + Agent
用途：在 Claude Code 中直接调用 Postman Collection 测试 API 端点、查看请求/响应、管理 API 文档。如果你主力做 RESTful API 或微服务架构开发，Postman MCP 把 API 调试也融入了 AI 编程流程。
安装：claude mcp add --transport http postman https://mcp.postman.com/mcp
🔗 官网：https://www.postman.com

△ Supabase — 开源BaaS后端

类型：MCP
用途：管理 Supabase 的 PostgreSQL 数据库（查询/Schema/RLS策略）、用户认证（邮箱/OAuth/SSO）、文件存储、Edge Functions。如果你用 Supabase 做后端，这个 MCP 让你的 Claude 可以直接操作数据库和执行迁移。
安装：claude mcp add supabase -- npx -y supabase-mcp-server
🔗 官网：https://supabase.com

△ Firebase — Google后端即服务

类型：MCP
用途：管理 Firebase 的 Firestore 数据库、Cloud Functions、Authentication、Hosting。Google 生态的全栈项目首选。
安装：claude mcp add firebase -- npx -y firebase-mcp-server
🔗 官网：https://firebase.google.com

△ Pinecone — 向量数据库

类型：MCP + Skill
用途：管理向量索引、插入/查询向量数据、实现语义搜索和 RAG（检索增强生成）。如果你在做 AI 应用（如智能客服、知识库问答），Pinecone 是构建 RAG Pipeline 的关键组件。
安装：claude mcp add pinecone -- npx -y pinecone-mcp-server
🔗 官网：https://www.pinecone.io

△ Stripe — 支付系统开发

类型：MCP + Skill
用途：Stripe 支付集成——支付意图创建、订阅管理、Webhook 测试。做电商、SaaS 订阅等需要支付的项目时使用。
安装：通过 Stripe 官方插件市场
🔗 官网：https://stripe.com

△ Laravel Boost — Laravel开发辅助

类型：MCP
用途：专为 Laravel 开发者打造——Artisan 命令智能提示、Eloquent ORM 关系辅助、路由文件生成、迁移文件管理、Blade 模板提示。PHP/Laravel 技术栈必备。
安装：claude mcp add laravel-boost -- npx -y laravel-boost-mcp
🔗 官网：npm 包 laravel-boost-mcp

△ HuggingFace Skills — AI模型与数据集

类型：MCP + Skill
用途：连接 HuggingFace 生态——搜索开源 AI 模型、数据集、Spaces 应用。当你的项目需要集成 AI 模型（文本分类、图像识别、语音处理等）时，可以直接在 Claude Code 中查找和引用 HuggingFace 模型。
安装：通过 HuggingFace MCP 接入
🔗 官网：https://huggingface.co

🔍 代码搜索与分析

△ Greptile — 自然语言代码搜索

类型：MCP
用途：用自然语言（中文也行）搜索和理解大型代码库。不需要知道确切的函数名——问”用户注册流程在哪些文件里？”就能找到相关代码。适合大型单体项目或多仓库场景。
安装：npx greptile-mcp-server --api-key=YOUR_KEY --github-token=YOUR_TOKEN
🔗 官网：https://app.greptile.com

🕷️ 数据抓取

△ Firecrawl — 网页转Markdown

类型：Skill
用途：将任意网站转换为 LLM 友好的 Markdown 格式——支持搜索、单页抓取、整站爬取、页面交互。当你需要让 Claude 参考某个网站的内容或文档时（比如爬取竞争对手的公开页面做竞品分析），Firecrawl 把网络变成知识源。
安装：npx -y firecrawl-cli@latest init -y --browser
🔗 官网：https://www.firecrawl.dev

✅ 代码质量增强

△ Qodo Skills — 代码质量/测试/安全/合规

类型：Skill
用途：一组专注于代码质量、测试用例生成、安全检查和合规性的技能。帮助 Claude 写出更健壮的测试（边界情况覆盖）、检查代码规范一致性、确保行业合规要求（如 GDPR、SOC2）。
安装：/plugin install qodo-skills@claude-plugins-official
🔗 官网：https://www.qodo.ai

△ Coderabbit — 40+分析器的AI代码评审（免费）

类型：Skill + Agent
用途：聚合 40+ 个静态分析器（包括各语言的 Linter、安全扫描器、复杂度分析器）的结果，由 AI 整合成一份综合评审报告。免费使用，提供比单一工具更全面的代码质量画像。
安装：通过 Coderabbit MCP 接入
🔗 官网：https://www.coderabbit.ai

📈 监控与产品分析

△ PostHog — 产品分析

类型：MCP + Skill + Agent
用途：查询用户行为数据、管理 Feature Flags（功能开关灰度发布）、查看 A/B 测试结果。在部署上线后验证新功能的效果——多少用户点击了新按钮、转化率有没有提升。
安装：claude mcp add --transport http posthog https://mcp.posthog.com/mcp
🔗 官网：https://posthog.com

△ PagerDuty — 部署风险评分

类型：MCP + Skill
用途：在 git commit / push 前对比 PagerDuty 的历史告警数据和当前变更 diff，预估部署风险。如果当前变更的文件最近在生产环境出过事故，它会给出高风险提示。
安装：通过 PagerDuty MCP 接入
🔗 官网：https://www.pagerduty.com

△ Sonatype Guide — 依赖漏洞分析

类型：MCP
用途：扫描项目依赖的已知 CVE 漏洞，推荐安全升级版本。基于 Sonatype 的全球最大漏洞数据库之一，确保供应链安全。
安装：通过 Sonatype MCP 接入
🔗 官网：https://www.sonatype.com

👥 按你的团队工具选择

以下插件用来连接你团队已经在用的协作工具——没有对应的工具就不用装。

△ Linear：Linear Issue 管理、Sprint 看板。MCP，HTTP 类型。🔗 linear.app
△ Atlassian：Jira Issue + Confluence 文档。MCP+Skill，HTTP 类型。🔗 atlassian.com
△ Asana：Asana 任务和项目管理。MCP，HTTP 类型。🔗 asana.com
△ Notion：Notion 页面和数据库操作。MCP+Skill，HTTP 类型。🔗 notion.so
△ Slack：Slack 消息搜索、频道浏览。MCP+Skill，HTTP 类型。🔗 slack.com
△ GitLab：GitLab 仓库、MR、CI/CD。MCP，HTTP 类型。🔗 gitlab.com
△ Circleback：会议记录、邮件、日历检索。MCP，HTTP 类型。🔗 circleback.ai

💡 安装方式均为：claude mcp add --transport http <名称> <MCP端点URL>，在 CC Switch 的 MCP 页签中添加对应 HTTP 类型服务器。

📝 LSP语言服务器（12 个 — 按你的编程语言选择）

LSP 服务器为 Claude Code 提供真实的 IDE 级类型检查、智能补全和跳转定义能力。按你的项目语言选对应的一个即可，不需要全装：

LSP 名称	适用语言	Claude Code 安装	官网
TypeScript LSP	TypeScript / JavaScript	`/lsp add typescript`	TypeScript 官方
Pyright LSP	Python	`/lsp add pyright`	Pyright
Gopls LSP	Go	`/lsp add gopls`	gopls
Rust Analyzer LSP	Rust	`/lsp add rust-analyzer`	rust-analyzer
ClangD LSP	C / C++	`/lsp add clangd`	clangd
PHP LSP	PHP	`/lsp add php`	Intelephense
Swift LSP	Swift	`/lsp add swift`	SourceKit-LSP
Kotlin LSP	Kotlin	`/lsp add kotlin`	Kotlin 官方
C# LSP	C#	`/lsp add csharp`	.NET 官方
JDTLS LSP	Java	`/lsp add jdtls`	Eclipse JDT.LS
Lua LSP	Lua	`/lsp add lua`	Lua 社区
Ruby LSP	Ruby	`/lsp add ruby`	Ruby 社区

💡 CC Switch 配置：所有 LSP 可在 CC Switch 的 LSP 管理页签中一键启用/禁用。

🧩 其他辅助类

以下插件用于特定场景——创建插件/自定义 Skill、教学引导、配置管理：

△ Agent SDK Dev：Claude Agent SDK 应用开发脚手架（TypeScript/Python）。Skill+Agent。/plugin install agent-sdk-dev@claude-plugins-official
△ Plugin Dev：Claude Code 插件开发套件（含 7 个子 Skill：MCP集成/Hook/Skill创建/测试/安全审计/发布）。Skill+Agent。/plugin install plugin-dev@claude-plugins-official
△ Skill Creator：自定义 Skill 的创建、改进和效果评估工具。Skill。/plugin install skill-creator@claude-plugins-official
△ Code Simplifier：3 个并行 Agent（复用检查/质量检查/效率检查）重构最近变更。Agent。内置命令 /simplify
△ Playground：生成交互式 HTML/CSS/JS 原型演示页面。Skill。/plugin install playground@claude-plugins-official
△ Claude Code Setup：自动分析代码库并推荐最优的 MCP/Skill/Hook 配置。Skill。/plugin install claude-code-setup@claude-plugins-official
△ Claude MD Management：CLAUDE.md 文件的定期质量审计和自动更新。Skill。/plugin install claude-md-management@claude-plugins-official
△ Explanatory Output Style：教学模式——Claude 会解释每个实现选择背后的”为什么”。Hook。/plugin install explanatory-output-style@claude-plugins-official
△ Learning Output Style：在关键决策点暂停，引导你主动编写代码。Hook。/plugin install learning-output-style@claude-plugins-official

🚀 推荐安装顺序

📅 第一天：最小可用（6 个核心）

# === MCP ===
claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking
claude mcp add context7 --transport http --header "CONTEXT7_API_KEY: xxx" context7 https://mcp.context7.com/mcp
claude mcp add playwright -- npx -y @anthropic-ai/playwright-mcp

# === Skill ===
/plugin install frontend-design@claude-plugins-official
/plugin install feature-dev@claude-plugins-official
npx skills add OthmanAdi/planning-with-files --skill planning-with-files-zh -g

📅 第一周：加上推荐（共 19 个）

# === MCP ===
claude mcp add --transport http figma https://mcp.figma.com/mcp
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# === Skill ===
/plugin marketplace add obra/superpowers-marketplace && /plugin install superpowers@superpowers-marketplace
/plugin install pr-review-toolkit@claude-plugins-official
/plugin install code-review@claude-plugins-official
/plugin install commit-commands@claude-plugins-official
/plugin install security-guidance@claude-plugins-official
/plugin install ralph-loop@claude-plugins-official
/plugin install hookify@claude-plugins-official
/plugin install vercel-labs/agent-skills

# === LSP ===
/lsp add typescript    # 或你用的语言

📅 后续：按需添加

每个迭代回顾：哪个环节重复劳动最多？装对应的插件。

💡 综上，我的核心建议是：**不要追求”装全”**。每个 MCP/Skill 都会消耗上下文窗口和启动时间。建议保持 2-3 个 MCP + 3-5 个 Skill 处于活跃状态。一个精心编写的 CLAUDE.md（定义你的项目规范、技术栈、代码风格）比 20 个插件更有价值。

Claude Code使用

Fri, 08 May 2026 15:58:13 +0800

1、CCSwicth

CC-Switch项目介绍
✨ 核心特性
CC-Switch从最初的简单API提供商切换工具，已经发展成功能完善的AI CLI管理平台，主要特性包括：

• 🚀 一键切换配置：点击即可切换不同API配置，从5分钟缩短到5秒，效率提升60倍
• ☁️ 云端同步配置（本文重点）：通过坚果云/OneDrive/Dropbox实现多设备自动同步，配置永不丢失
• 🎯 多工具支持：完美支持Claude Code、Codex、Gemini CLI三大AI编程工具
• 🔧 MCP服务器管理：统一管理Model Context Protocol服务器，支持stdio、HTTP、SSE三种传输类型
• ⚡ API速度测试：内置端点测试功能，自动识别最快的API提供商
• 📦 配置导入导出：一键导出配置分享给团队，自动备份最近10个版本
• 💾 双层架构：SQLite + JSON双层设计，同步效率高性能好
• 🌍 多平台支持：完整支持Windows、macOS、Linux（包括WSL）

2、MCP

通过CCSwicth 进行安装

Claude Code推荐MCP

3、skills

1、ui-ux-pro-max

67 种 UI 风格——玻璃化、黏土化、极简主义、粗犷主义、拟物化、Bento 网格、暗黑模式、AI 原生 UI 等等
161 种颜色方案- 与 161 种产品类型一一对应的行业特定颜色方案
57 种字体搭配- 精选的字体组合，并导入了 Google Fonts 字体
25 种图表类型- 仪表盘和分析的建议
15 种技术栈- React、Next.js、Astro、Vue、Nuxt.js、Nuxt UI、Svelte、SwiftUI、React Native、Flutter、HTML+Tailwind、shadcn/ui、Jetpack Compose、Angular、Laravel
99 条用户体验指南——最佳实践、反模式和无障碍规则
161 条推理规则- 行业特定设计系统生成（v2.0 新增）

V2Ray 自建节点教程

Thu, 16 Apr 2026 17:23:14 +0800

V2Ray 自建节点教程

1. 前期准备

1.1 所需材料

材料	说明
云服务器	支持 Linux（推荐 Ubuntu 20.04+ 或 Debian 11+）
SSH 工具	FinalShell、Xshell、PuTTY 或 PowerShell

1.2 服务器要求

最低配置：
- CPU: 1核
- 内存: 512MB
- 带宽: 1Mbps+
- 硬盘: 10GB+

推荐配置：
- CPU: 1核
- 内存: 1GB+
- 带宽: 5Mbps+
- 硬盘: 20GB+

1.3 连接服务器

# Windows 使用 PuTTY 或 PowerShell
ssh root@你的服务器IP

# macOS/Linux 终端直接连接
ssh root@你的服务器IP -p 22

1.4 开放端口

# 防火墙放行常用端口
ufw allow 22/tcp    # SSH
ufw allow 80/tcp    # HTTP（证书申请）
ufw allow 443/tcp   # HTTPS/TLS

2. 服务器配置选择

2.1 协议对比

协议	安全性	速度	抗封锁	配置难度
VMess	高	中	中	中
VLESS	高	快	中	中
Trojan	高	快	高	中
Shadowsocks	中	快	中	低
WebSocket+TLS	高	快	高	高

2.2 传输方式对比

传输方式	伪装程度	速度	抗封锁	适用场景
TCP	无	快	中	低审查环境
WebSocket	高（像浏览流量）	中	高	高审查环境
HTTP/2	高	快	高	中等审查环境
gRPC	高	快	高	高审查环境

2.3 推荐组合

推荐指数：★★★★★  最佳选择（有域名）
VLESS + WebSocket + TLS + Cloudflare

推荐指数：★★★★★  极致性能+抗封锁
VLESS + XTLS + REALITY（无需域名，最强伪装）

推荐指数：★★★★☆  无域名方案（自签名证书）
VLESS + WebSocket + TLS（自签名证书）
客户端需开启"允许不安全连接"

推荐指数：★★★★☆  入门选择
Shadowsocks + chacha20-poly1305

推荐指数：★★★☆☆  快速测试
VLESS + TCP（最简单，但隐蔽性差）

推荐指数：★★★☆☆  V2Ray 5.x 用户
VLESS + TCP (V2Ray 5.x 不再支持 VMess)

2.4 VLESS + XTLS + REALITY（进阶方案）

如果你追求极致的性能和抗封锁能力，推荐使用 VLESS + XTLS + REALITY 组合。它是目前公认的、抗封锁能力最强的方案之一。

核心原理

REALITY（伪装）

不再需要域名和 TLS 证书
直接”借用”真实网站的证书和 TLS 指纹
通过模仿 www.microsoft.com、www.apple.com 等网站的 TLS 握手
流量与访问这些官网完全一致，无法识别和封锁

XTLS（加速）

消除”二次加解密”冗余（TLS 加密 + WebSocket 封装）
穿透已加密流量，降低 CPU 负载
显著提升传输速度和降低延迟

方案对比

特性	VLESS + WS + TLS	VLESS + XTLS + REALITY
性能	相对较低，有额外性能开销	极高，XTLS 避免二次加解密
隐蔽性	较强，但 WebSocket 特征可能被识别	极强，最先进伪装技术之一
端口	通常需要 443 端口	可用任意端口（如 8443），更灵活
证书	需要域名和证书	无需域名，无需管理证书
CDN 支持	可以套 CDN 隐藏真实 IP	无法套 CDN，会破坏伪装
部署难度	简单	略复杂（需生成密钥、配置目标网站）

风险与应对

风险	降低方法
DNS 白名单检测	选择大型、IP 段多的网站作为 Target（如 microsoft.com、apple.com、Cloudflare 域名）
中间人攻击检测	定期更换 REALITY 公钥/私钥
单点故障	保留 VLESS+WS+TLS 节点作为备用，两者搭配使用

手动配置（JSON）

{
  "inbounds": [
    {
      "listen": "0.0.0.0",
      "port": 36606,
      "protocol": "vless",
      "settings": {
        "clients": [
          {
            "id": "你的UUID",
            "flow": "xtls-rprx-vision"
          }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp"
      },
      "security": "reality",
      "realitySettings": {
        "show": false,
        "dest": "www.apple.com:443",
        "xver": 0,
        "serverNames": ["www.apple.com"],
        "privateKey": "你的私钥",
        "publicKey": "你的公钥",
        "shortId": "abc123"
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

密钥生成

在 Linux 服务器上生成密钥对：

# 生成私钥（32字节，Base64编码）
openssl rand -base64 32

# 生成公钥（25519椭圆曲线）
# Xray 会根据私钥自动生成公钥

或在 3X-UI 面板中点击 “Generate key” 自动生成。

客户端配置要点

参数	值
协议	VLESS
地址	服务器 IP
端口	你设置的端口（如 36606）
UUID	服务端配置的 UUID
Flow	`xtls-rprx-vision`（启用 XTLS）
传输	TCP（不是 WebSocket）
安全	REALITY
SNI	与 Target 域名一致（如 www.apple.com）
uTLS	`chrome` / `firefox` / `safari`

注意：客户端的 Flow 参数 xtls-rprx-vision 是启用 XTLS 加速的关键，必须填写。

2.5 无域名方案说明

适用场景：

没有域名
不想使用 Cloudflare
快速部署

配置要点：

节点类型	端口	TLS	说明
TCP	10086	关闭	最简单，但容易被封锁
WS+TLS	443	自签名	较安全，客户端需 allowInsecure

客户端配置：

自签名证书需要勾选”允许不安全连接”
使用 IP 地址而非域名

2.6 有域名方案（Cloudflare）

适用场景：

已有域名
需要更好隐蔽性
不想暴露服务器真实 IP

配置要点：

将域名接入 Cloudflare
DNS 解析到服务器 IP，开启代理（橙色云）
申请 Let’s Encrypt 证书或使用 Cloudflare Origin Certificate
配置 Nginx 反向代理

优势：

Cloudflare 隐藏真实服务器 IP
CDN 加速
更好的抗封锁能力

3. 自建节点（手动配置）

本章节适用于不使用图形面板，直接手动配置 V2Ray 的用户。
如果使用 3X-UI，请跳转到下一章节。

3.1 UUID 详解

UUID 是什么？
UUID 是 VLESS 协议的用户身份标识，像一把钥匙：

服务器配置允许的 UUID 列表
客户端连接时提供自己的 UUID
服务器验证 UUID 是否在白名单中

格式示例：

40552b9c-80f4-419f-b112-a6bba2b99338

生成方法：

cat /proc/sys/kernel/random/uuid

配置示例：

{
  "inbounds": [{
    "port": 10086,
    "protocol": "vless",
    "settings": {
      "clients": [
        {"id": "你的UUID", "email": "user1"},
        {"id": "他的UUID", "email": "user2"}
      ],
      "decryption": "none"
    }
  }]
}

说明：

email 字段不是必填，可省略（仅用于标识用户）
可以添加多个 UUID，支持多人共用
删除某个 UUID 即可禁止对应用户访问
TCP 和 WS+TLS 节点的 UUID 可以共用或分开

管理多人访问：

需求	操作
添加新用户	在 clients 中添加新 UUID，重启服务
禁止某用户	删除对应 UUID，重启服务
限制来源 IP	使用 ufw 防火墙规则

3.2 一键安装 V2Ray（官方脚本）

# 下载安装脚本
bash <(curl -L https://raw.githubusercontent.com/v2fly/fhs-install-v2ray/master/install-release.sh)

# 启动服务
systemctl start v2ray
systemctl enable v2ray

# 查看状态
systemctl status v2ray

3.3 安装 V2Ray 5.x（手动安装）

# 下载 V2Ray 5.x
wget https://github.com/v2fly/v2ray-core/releases/download/v5.10.0/v2ray-linux-64.zip
unzip v2ray-linux-64.zip
mv v2ray /usr/local/bin/
mv v2ctl /usr/local/bin/
chmod +x /usr/local/bin/v2ray /usr/local/bin/v2ctl

# 创建 systemd 服务文件（一键创建）
cat > /etc/systemd/system/v2ray.service << 'EOF'
[Unit]
Description=V2Ray Service
After=network.target

[Service]
ExecStart=/usr/local/bin/v2ray run -config /etc/v2ray/config.json
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

# 重载服务
systemctl daemon-reload
systemctl enable v2ray
systemctl start v2ray

3.4 VLESS + TCP 配置

{
  "inbounds": [
    {
      "listen": "0.0.0.0",
      "port": 10086,
      "protocol": "vless",
      "settings": {
        "clients": [
          {
            "id": "你的UUID",
            "flow": ""
          }
        ],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "tcp"
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

3.5 VLESS + WebSocket + TLS 配置

方案一：无域名（自签名证书）

{
  "log": {"loglevel": "warning"},
  "inbounds": [
    {
      "port": 443,
      "listen": "0.0.0.0",
      "protocol": "vless",
      "settings": {
        "clients": [{"id": "你的UUID"}],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "ws",
        "wsSettings": {
          "path": "/v2ray"
        },
        "security": "tls",
        "tlsSettings": {
          "certificates": [
            {
              "certificateFile": "/etc/ssl/certs/cert.pem",
              "keyFile": "/etc/ssl/private/key.pem"
            }
          ]
        }
      }
    }
  ],
  "outbounds": [{"protocol": "freedom"}]
}

方案二：有域名（Let’s Encrypt/CF 证书）

{
  "log": {"loglevel": "warning"},
  "inbounds": [
    {
      "port": 443,
      "listen": "0.0.0.0",
      "protocol": "vless",
      "settings": {
        "clients": [{"id": "你的UUID"}],
        "decryption": "none"
      },
      "streamSettings": {
        "network": "ws",
        "wsSettings": {
          "path": "/v2ray"
        },
        "security": "tls",
        "tlsSettings": {
          "serverName": "你的域名",
          "alpn": ["h2", "http/1.1"]
        }
      }
    }
  ],
  "outbounds": [{"protocol": "freedom"}]
}

3.6 双节点配置（同时监听 TCP + WS+TLS）

同时启用 TCP 和 WebSocket+TLS 两种节点：

{
    "log": {"loglevel": "warning"},
    "inbounds": [
        {
            "port": 10086,
            "listen": "0.0.0.0",
            "protocol": "vless",
            "settings": {
                "clients": [{"id": "第一个UUID"}],
                "decryption": "none"
            },
            "streamSettings": {
                "network": "tcp"
            }
        },
        {
            "port": 443,
            "listen": "0.0.0.0",
            "protocol": "vless",
            "settings": {
                "clients": [{"id": "第二个UUID"}],
                "decryption": "none"
            },
            "streamSettings": {
                "network": "ws",
                "wsSettings": {
                    "path": "/v2ray"
                },
                "security": "tls",
                "tlsSettings": {
                    "certificates": [
                        {
                            "certificateFile": "/etc/ssl/certs/cert.pem",
                            "keyFile": "/etc/ssl/private/key.pem"
                        }
                    ]
                }
            }
        }
    ],
    "outbounds": [{"protocol": "freedom"}]
}

3.7 VMess + TCP 配置（V2Ray 4.x 旧版）

{
  "inbounds": [
    {
      "listen": "0.0.0.0",
      "port": 10086,
      "protocol": "vmess",
      "settings": {
        "clients": [
          {
            "id": "你的UUID",
            "alterId": 0
          }
        ]
      },
      "streamSettings": {
        "network": "tcp"
      }
    }
  ],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

3.8 Shadowsocks 服务器搭建

3.8.1 安装 Shadowsocks（单用户）

# Ubuntu/Debian
apt update
apt install -y shadowsocks-libev

# 启动
ss-server -c /etc/shadowsocks-libev/config.json

3.8.2 安装 simple-obfs（混淆插件）

# 安装依赖
apt install -y build-essential autoconf libtool

# 下载编译
git clone https://github.com/shadowsocks/simple-obfs.git
cd simple-obfs
./autogen.sh
./configure && make
make install

# 配置使用插件

3.8.3 Shadowsocks + chacha20-poly1305 配置

{
  "server": "0.0.0.0",
  "server_port": 8388,
  "password": "你的密码",
  "method": "chacha20-ietf-poly1305",
  "timeout": 300,
  "fast_open": true
}

3.8.4 Shadowsocks + TLS 插件配置

{
  "server": "0.0.0.0",
  "server_port": 8388,
  "password": "你的密码",
  "method": "chacha20-ietf-poly1305",
  "timeout": 300,
  "fast_open": true,
  "plugin": "obfs-local",
  "plugin_opts": "obfs=tls;failover=你的域名;failover=127.0.0.1"
}

3.8.5 启动命令

# 前台运行
ss-server -c /etc/shadowsocks-libev/config.json

# 后台运行
nohup ss-server -c /etc/shadowsocks-libev/config.json &

# 查看运行状态
ps aux | grep ss-server
netstat -tlnp | grep 8388

3.9 Trojan 服务器搭建

3.9.1 端口冲突说明

冲突原因：

V2Ray WS+TLS 默认用 443 端口
Trojan 默认也用 443 端口
两者不能同时使用 443

解决方案：

方案	V2Ray WS+TLS	Trojan	说明
方案一	改用 8443	用 443	Trojan 优先
方案二	用 80 端口（无TLS）	用 443	V2Ray 无加密
方案三	保持 443	不用	推荐，只用 V2Ray

推荐： 如果只用 VLESS，不需要 Trojan，用方案一让 V2Ray WS+TLS 改端口。

3.9.2 安装 Trojan

# 下载
wget https://github.com/trojan-gfw/trojan/releases/download/v1.16.0/trojan-1.16.0-linux-amd64.tar.xz
tar xf trojan-1.16.0-linux-amd64.tar.xz
mv trojan /usr/local/bin/

# 创建配置目录
mkdir -p /etc/trojan

3.9.3 配置文件 /etc/trojan/config.json

cat > /etc/trojan/config.json << 'EOF'
{
    "run_type": "server",
    "local_addr": "0.0.0.0",
    "local_port": 443,
    "remote_addr": "127.0.0.1",
    "remote_port": 80,
    "password": [
        "你的密码"
    ],
    "ssl": {
        "cert": "/etc/ssl/certs/cert.pem",
        "key": "/etc/ssl/private/key.pem",
        "sni": "example.com",
        "alpn": ["h2", "http/1.1"]
    }
}
EOF

3.9.4 启动 Trojan

方法一：前台运行（测试用）

/usr/local/bin/trojan -c /etc/trojan/config.json

方法二：后台运行

nohup /usr/local/bin/trojan -c /etc/trojan/config.json &

方法三：systemd 服务（推荐）

cat > /etc/systemd/system/trojan.service << 'EOF'
[Unit]
Description=Trojan Service
After=network.target

[Service]
ExecStart=/usr/local/bin/trojan -c /etc/trojan/config.json
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable trojan
systemctl start trojan
systemctl status trojan

3.9.5 客户端连接信息

项目	值
地址	服务器IP
端口	443
密码	你设置的密码
TLS	开启

导入链接：

trojan://你的密码@服务器IP:443#Trojan

3.9.6 管理多用户

编辑 /etc/trojan/config.json，在 password 数组中添加多个密码：

{
    "password": [
        "密码1",
        "密码2",
        "密码3"
    ]
}

添加后重启：

systemctl restart trojan

3.9.7 常用命令

# 启动/停止/重启
systemctl start trojan
systemctl stop trojan
systemctl restart trojan

# 查看状态
systemctl status trojan

# 查看端口
netstat -tlnp | grep trojan

# 查看运行
ps aux | grep trojan

4. 3X-UI 一键部署

3X-UI 是图形化管理面板，自带 Xray 内核，无需单独安装 V2Ray。

4.1 面板推荐对比

面板	基于	特点	安装难度
3X-UI	Xray	功能完整，界面友好	简单
x-ui	Xray	轻量级，简单易用	简单
Marzban	Xray	支持订阅、流量限制、多用户	中等
s-ui	sing-box	现代化界面	简单

4.2 3X-UI 安装

适用场景：

需要图形化界面管理节点
需要 SSL 证书配置
需要流量统计和用户管理
不想手动编辑配置文件

安装命令：

sudo apt update && sudo apt upgrade -y
sudo apt install curl -y


bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

安装交互设置：

是否自定义面板端口：y → 如 54321
设置用户名、密码
面板路径：默认回车
SSL：先选 2（自签）或 3（稍后配置）

访问地址：

http://服务器IP:54321
https://域名:54321

4.3 3X-UI 常用命令

# 面板服务
systemctl start x-ui    # 启动
systemctl stop x-ui     # 停止
systemctl restart x-ui  # 重启
systemctl status x-ui   # 状态

# 实时日志
journalctl -u x-ui -f

4.4 3X-UI 配置 SSL 证书

1. 安装 acme.sh

curl https://get.acme.sh | sh
source ~/.bashrc

2. 注册邮箱（必须）

acme.sh --register-account -m 你的邮箱

3. 放行 80 端口

sudo ufw allow 80/tcp

4. 申请证书（standalone 模式）

acme.sh --issue -d 你的域名 --standalone

5. 证书默认路径

/root/.acme.sh/你的域名_ecc/
├── fullchain.cer  # 证书链
├── 你的域名.key   # 私钥

6. 创建证书目录并复制

mkdir -p /etc/3x-ui/certs

cp /root/.acme.sh/你的域名_ecc/fullchain.cer /etc/3x-ui/certs/cert.pem
cp /root/.acme.sh/你的域名_ecc/你的域名.key /etc/3x-ui/certs/key.pem

7. 设置安全权限

chmod 644 /etc/3x-ui/certs/cert.pem
chmod 600 /etc/3x-ui/certs/key.pem

8. 面板配置

面板设置 → SSL证书设置
证书路径：/etc/3x-ui/certs/cert.pem
私钥路径：/etc/3x-ui/certs/key.pem

9. 重启面板

systemctl restart x-ui

4.5 3X-UI 添加入站（VLESS+WS+TLS）

入站配置步骤：

基本信息
- 协议：vless
- 端口：443
- 监听：0.0.0.0
- 备注：VLESS-WS-TLS
传输配置
- Network：ws
- 路径：/v2ray
- Host：你的域名
TLS 配置
- 启用TLS：勾选
- 证书/私钥路径：同上
客户配置
- Add Client → 生成 UUID
- Flow：none
- Encryption：none
验证端口监听

netstat -tlnp | grep 443

4.6 3X-UI 添加入站（VLESS+XTLS+REALITY）

如果追求极致性能和抗封锁能力，推荐使用 VLESS+XTLS+REALITY。无需域名和证书，通过借用真实网站的 TLS 指纹实现最强伪装。

入站配置步骤

基本信息
- 协议：vless
- 端口：36606（或自定义高位端口）
- 监听：0.0.0.0
- 备注：VLESS-XTLS-REALITY
传输配置
- Network：TCP (RAW)（不是 WebSocket/XHTTP）
安全设置
- 安全：选择 Reality
REALITY 参数

参数	说明	示例
uTLS	模仿的浏览器指纹	`chrome`
Target	借用的目标网站（必须是真实 HTTPS）	`www.apple.com:443`
SNI	必须与 Target 的域名一致	`www.apple.com`
Public Key	点击生成	（自动生成）
Private Key	服务器端保留	（自动生成）
Short IDs	可留空或填短字符串	`abc123`

客户端配置
- Add Client → 生成 UUID
- Flow：xtls-rprx-vision（启用 XTLS 加速的关键）
- Encryption：none

Target 参数说明

参数	含义
Target	REALITY 借用的外部真实网站（固定 443 端口）
你的代理端口	客户端连接的端口（如 36606）

注意：Target 保持 www.apple.com:443（或类似），不要改为你的代理端口！

风险与应对

风险	降低方法
DNS 白名单检测	选择大型网站作为 Target（如 microsoft.com、apple.com）
中间人攻击检测	定期更换 REALITY 公钥/私钥
单点故障	保留 VLESS+WS+TLS 节点作为备用

v2rayN 客户端配置

参数	值
协议	VLESS
地址	服务器 IP
端口	36606
UUID	面板生成的 UUID
Flow	`xtls-rprx-vision`
传输	TCP
安全	REALITY
SNI	`www.apple.com`
uTLS	`chrome`

4.7 3X-UI 端口 443 冲突解决

现象：

Failed to listen on 0.0.0.0:443

排查命令：

sudo lsof -i :443

解决方案（手动 V2Ray 占用）：

systemctl stop v2ray
systemctl disable v2ray
systemctl restart x-ui

4.8 3X-UI 客户端配置（v2rayN）

面板入站 → 操作 → 查看配置 → 复制链接
v2rayN → 从剪贴板导入
右键节点 → 编辑 → TLS
- 勾选：跳过证书验证（allowInsecure）
- SNI：填写域名
测试连通性

4.9 Marzban 安装（备选）

安装命令：

# 一键安装
bash <(curl -s https://raw.githubusercontent.com/Gozargah/Marzban-scripts/master/marzban.sh)

基本命令：

# 查看状态
marzban status

# 启动/停止/重启
marzban start
marzban stop
marzban restart

# 查看日志
marzban logs

访问面板：

默认端口：8000
用户名：admin
密码：安装时生成

特点：

支持 VLESS、Trojan、Shadowsocks、VMess
支持订阅、流量限制、到期时间
支持 API 可对接 otherpanel 等前端

4.10 面板常用命令速查

# 面板服务（3X-UI/x-ui）
systemctl start x-ui
systemctl stop x-ui
systemctl restart x-ui
systemctl status x-ui

# 实时日志
journalctl -u x-ui -f

# 端口监听
netstat -tlnp | grep 443
netstat -tlnp | grep 54321

# 防火墙放行
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 54321/tcp

# 证书复制通用模板
cp ~/.acme.sh/域名_ecc/fullchain.cer /etc/3x-ui/certs/cert.pem
cp ~/.acme.sh/域名_ecc/域名.key /etc/3x-ui/certs/key.pem

5. 公共部分

5.1 域名购买与解析

域名注册商：

Namesilo（性价比高）
阿里云
Cloudflare（免费）

添加 DNS 解析：

登录域名管理后台
添加 A 记录：
- 主机记录：@ 或 www
- 记录值：服务器公网 IP
验证解析：

ping 你的域名

5.2 TLS 证书申请（acme.sh）

安装 acme.sh：

curl https://get.acme.sh | sh
source ~/.bashrc

注册账号：

acme.sh --register-account -m 你的邮箱

申请证书（standalone 模式）：

# 放行80端口
ufw allow 80/tcp

# 申请
acme.sh --issue -d 你的域名 --standalone

证书路径：

/root/.acme.sh/你的域名_ecc/
├── fullchain.cer  # 证书链
├── 你的域名.key   # 私钥

5.3 客户端配置生成规则

VMess 链接格式

vmess://base64({"v": "2", "ps": "名称", "add": "IP", "port": "端口", "id": "UUID", "aid": 0, "net": "tcp/ws", "type": "none", "host": "", "path": "/路径", "tls": "tls/aio"})

VLESS 链接格式

vless://UUID@IP:端口?encryption=none&type=tcp/ws&path=/路径#名称

Trojan 链接格式

trojan://密码@IP:端口#名称

Shadowsocks 链接格式

ss://base64(method:password@IP:端口)#名称

5.4 常用端口

端口	用途	备注
80	HTTP	可用于 ACME 申请证书
443	HTTPS/TLS	常用伪装端口
8443	自定义 TLS	可替代 443
10086	VMess/VLESS TCP	自定义端口
54321	3X-UI 面板	默认面板端口
8000	Marzban 面板	默认面板端口
8388	Shadowsocks	默认端口

5.5 客户端下载与配置

各平台推荐客户端

操作系统	推荐客户端	下载来源	简要特点
Windows	v2rayN	GitHub Releases	功能强大，图形化界面，支持多种协议和订阅
	Clash for Windows	GitHub Releases	界面美观，基于规则分流，对新手友好
macOS	V2rayU	GitHub Releases 或 `brew install --cask v2rayu`	经典 macOS 客户端，稳定易用
	ClashX	GitHub Releases	轻量简洁，macOS 热门选择
Android	v2rayNG	Google Play 或 GitHub	功能全面，支持二维码扫描和订阅
iOS	Shadowrocket	App Store (付费)	功能强大，iOS 主流选择
	Quantumult X	App Store (付费)	专业复杂，适合高阶用户
Linux	v2rayL	GitHub Releases	图形化界面，对 Linux 桌面用户友好
	Qv2ray	GitHub Releases	跨平台，功能强大（已停止维护）

核心提示：上述客户端基本免费且开源，务必从官方 GitHub 下载最新版本。

下载步骤（以 v2rayN 为例）

访问发布页面：打开 github.com/2dust/v2rayN/releases
选择版本：下载最新的 .zip 或 .7z 压缩包（解压即用版）
运行客户端：解压后运行 v2rayN.exe 即可

客户端配置步骤

添加节点：手动输入或扫描二维码导入节点信息
填写服务端信息：
- 类型：VLESS
- 地址：你的服务器 IP 或域名
- 端口：10086（TCP）或 443（WS+TLS）
- UUID：服务端配置的 UUID
- 传输：TCP 或 WebSocket
- TLS：TCP 节点关闭，WS+TLS 节点开启
- 允许不安全连接：仅 WS+TLS（自签名证书）时需要
测试连接：点击”使用”或直接启动代理测试

注意事项

时间同步：
V2Ray 对时间同步有严格要求，客户端和服务器的系统时间误差不能超过 1 分钟，否则可能无法连接。请在设备设置中开启”自动设置时间”功能。

网络环境：
访问 GitHub 网站有时可能不太稳定，这是正常现象，可能需要一些耐心。

macOS 安全警告：
首次打开非 App Store 下载的应用时，可能会提示”文件已损坏”。这时需要在”系统设置” > “隐私与安全性”中手动允许运行该应用。

客户端使用前提：
客户端本身只是一个工具，需要配合可用的服务器节点或订阅链接才能使用。

6. 问题清单与解决方案

问题 1：geoip.dat 文件损坏

现象：

Failed to load geoip.dat: Not Found
或
geoip.dat only has 9 bytes

原因：
geoip.dat 文件下载不完整或服务器返回了 404 页面

解决方案：

方法一：重新下载 geoip.dat

wget https://github.com/v2fly/geoip/raw/master/geoip.dat
mv geoip.dat /etc/v2ray/geoip.dat

方法二：使用域名路由（绕过 geoip）

在路由规则中使用 domainStrategy: "AsIs"
使用 Cloudflare 等 CDN 隐藏服务器 IP
配置国内直连规则时不依赖 geoip

排查方法：

# 检查文件大小
ls -la /etc/v2ray/geoip.dat

# 正确大小应该 > 1MB
# 如果是 9 bytes 则是下载失败

问题 2：V2Ray 5.x 不支持 VMess 协议

现象：

 VLESS tick/tack required
 or
 VMess not supported after V2Ray 5.0

原因：
V2Ray 5.x 版本移除了 VMess 协议支持，必须使用 VLESS

解决方案：

服务器端改用 VLESS 协议

{
  "inbounds": [{
    "protocol": "vless",
    "settings": {
      "clients": [{
        "id": "你的UUID",
        "flow": ""
      }]
    }
  }]
}

客户端也必须选择 VLESS 类型
或降级到 V2Ray 4.x

bash <(curl -L https://raw.githubusercontent.com/v2fly/fhs-install-v2ray/master/install-release.sh) --version 4.45.2

排查方法：

# 检查 V2Ray 版本
v2ray version
# 或
/usr/local/bin/v2ray version

问题 3：V2Ray 5.x 命令行参数变更

现象：

unknown flag: -config

原因：
V2Ray 5.x 更改了命令语法，从 -config 改为 run -config

解决方案：

V2Ray 4.x：

v2ray -config /etc/v2ray/config.json

V2Ray 5.x：

v2ray run -config /etc/v2ray/config.json

排查方法：

# 查看帮助
v2ray help
v2ray run --help

问题 4：端口 1080 被占用

现象：

port is already in use
listen tcp 0.0.0.0:1080: bind: address already in use

原因：

其他程序占用了 1080 端口（如 v2rayN、Shadowrocket 等）
系统中已有其他代理程序

解决方案：

方法一：更改代理端口

客户端使用其他端口如 10808、2080 等

方法二：查找占用进程

# Windows
netstat -ano | findstr :1080
tasklist | findstr PID

# Linux
lsof -i :1080
netstat -tlnp | grep 1080

方法三：关闭占用程序

# Windows 结束进程
taskkill /PID 进程ID /F

问题 5：systemd 启动失败但手动运行成功

现象：

systemctl start v2ray 失败，状态 failed (Result: exit-code)
日志显示 Failed to build TLS config
但直接运行 /usr/local/bin/v2ray run -config ... 成功

原因：
/etc/ssl/private/ 目录权限为 700，systemd 运行时（nobody 用户）无法进入，导致无法读取 key.pem。

解决：

chmod 755 /etc/ssl/private/
systemctl restart v2ray

排查方法：

# 查看详细日志
journalctl -u v2ray -n 50

# 检查进程
ps aux | grep v2ray

# 手动运行测试
/usr/local/bin/v2ray run -config /usr/local/etc/v2ray/config.json

问题 6：curl 测试返回结果解读

WS+TLS 节点：

curl -k https://服务器IP/v2ray -v
HTTP/1.1 400 Bad Request

这是正常的！说明 443 端口正常，正在等待 WebSocket 握手。

TCP 节点：

curl http://服务器IP:10086 -v
curl: (52) Empty reply from server

这也是正常的！VLESS TCP 不是 HTTP 服务器，curl 无法完整测试。

结论：

curl 返回 Bad Request = 端口正常
curl 返回 Empty reply = 端口正常
使用客户端（v2rayN）测试连接

问题 7：WebSocket 路径不正确

现象：

websocket: connection refused
或
failed to handshake

原因：

服务器 path 与客户端不匹配
Nginx/Caddy 未正确代理 WebSocket

解决方案：

服务器 Nginx 配置：

location /v2ray {
    proxy_pass http://127.0.0.1:10086;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    keepalive_timeout 60s;
}

问题 8：TLS 证书验证失败

现象：

tls: failed to verify certificate
或
certificate not trusted

原因：

证书过期
证书与域名不匹配
证书链不完整

解决方案：

检查证书有效期

openssl x509 -in cert.pem -noout -dates

重新申请证书

~/.acme.sh/acme.sh --renew -d 你的域名 --force

客户端跳过证书验证（仅测试用）

{
  "tlsSettings": {
    "allowInsecure": true
  }
}

问题 9：geoip.dat 路由规则不生效

现象：

国内 IP 未走直连
国外 IP 未走代理

原因：

geoip.dat 文件损坏或版本过旧
路由规则配置错误

解决方案：

更新 geoip.dat

wget https://github.com/v2fly/geoip/raw/master/geoip.dat -O /etc/v2ray/geoip.dat
systemctl restart v2ray

使用域名规则替代

"routing": {
  "domainStrategy": "IPIfNonMatch",
  "rules": [
    {
      "type": "field",
      "outboundTag": "direct",
      "domain": ["geosite:cn"]
    },
    {
      "type": "field",
      "outboundTag": "direct",
      "ip": ["geoip:private", "geoip:cn"]
    }
  ]
}

问题 10：Shadowsocks 密码错误

现象：

failed to handshake: cipher method chacha20-ietf-poly1305 not supported
或
authentication error

原因：

客户端与服务端密码不一致
加密方式不支持

解决方案：

确保密码完全一致
确认加密方式两端匹配

服务端配置：

{
  "server": "0.0.0.0",
  "password": "你的密码",
  "method": "chacha20-ietf-poly1305"
}

问题 11：服务器带宽不足

现象：

速度慢、卡顿
延迟高

原因：

服务器带宽限制
网络拥堵
线路不稳定

解决方案：

选择优质线路（CN2、CN2 GIA）
开启 BBR 加速

echo "net.core.default_qdisc=fq" >> /etc/sysctl.conf
echo "net.ipv4.tcp_congestion_control=bbr" >> /etc/sysctl.conf
sysctl -p

使用 Cloudflare CDN 加速

问题 12：客户端导入节点格式不被识别

现象：

导入 vmess:// 链接无效
导入后节点信息不完整

原因：

链接格式不正确
Base64 编码错误

解决方案：

使用正确的链接格式
检查 Base64 编码是否正确
手动填写节点信息

Base64 解码验证：

# Linux/macOS
echo "base64字符串" | base64 -d

# 在线工具
# https://www.base64decode.org/

问题 13：VLESS 协议 UUID 格式错误

现象：

Invalid user
或
UUID format error

原因：

UUID 格式不符合标准
客户端与服务端 UUID 不一致

解决方案：

生成标准 UUID

# Linux
uuidgen

# 在线生成
# https://www.uuidgenerator.net/

# 标准格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# 例如：40552b9c-80f4-419f-b112-a6bba2b99338

确保客户端与服务端 UUID 完全一致

问题 14：新增 VLESS+WS+TLS 节点无法连接（UUID 不生效）

现象：

服务器已配置双节点（TCP 和 WS+TLS），原有 WS+TLS 节点（UUID A）正常工作
新增一个 WS+TLS 节点（UUID B），客户端配置正确但无法连接，延迟测试显示 -1
将客户端 UUID 改为 UUID A 后可以正常连接
服务器配置文件中已添加 UUID B，systemctl status v2ray 显示服务运行正常

排查流程：

确认客户端配置正确：复制正常工作的节点，仅修改 UUID，仍无法连接 → 排除客户端传输配置问题
交换 UUID 测试：
- 将正常节点的 UUID 改为 UUID B → 无法连接
- 将异常节点的 UUID 改为 UUID A → 可以连接
- 结论：UUID B 在服务端未生效
检查服务端配置文件：cat /etc/v2ray/config.json 显示 UUID B 已正确添加
检查服务实际使用的配置文件路径：
```
systemctl status v2ray
```
输出显示：/usr/local/bin/v2ray run -config /usr/local/etc/v2ray/config.json
→ 发现服务实际读取的是 /usr/local/etc/v2ray/config.json，而非 /etc/v2ray/config.json
检查实际配置文件内容：
```
cat /usr/local/etc/v2ray/config.json | grep -E '"id":'
```
发现该文件中只有 UUID A，没有 UUID B
修改正确的配置文件，添加 UUID B，重启服务后问题解决

排查命令汇总：

# 查看服务实际使用的配置文件路径
systemctl status v2ray

# 检查实际配置文件中的 UUID 列表
cat /usr/local/etc/v2ray/config.json | grep -E '"id":'

# 检查服务监听的端口
ss -tlnp | grep v2ray

# 查看服务日志（无错误不代表配置被加载）
journalctl -u v2ray -n 50 --no-pager

原因：

系统中存在多个 V2Ray 配置文件（/etc/v2ray/config.json 和 /usr/local/etc/v2ray/config.json）
systemd 服务单元中指定的配置文件路径是 /usr/local/etc/v2ray/config.json
用户修改了错误的配置文件（/etc/v2ray/config.json），导致修改未生效

解决办法：

确认服务实际使用的配置文件路径：
```
systemctl status v2ray | grep "config"
```
编辑正确的配置文件（例如 /usr/local/etc/v2ray/config.json）：
```
sudo nano /usr/local/etc/v2ray/config.json
```

添加新 UUID 到 clients 数组：

"clients": [
  {"id": "原有UUID", "email": "1"},
  {"id": "新UUID", "email": "2"}
],

检查 JSON 格式：

cat /usr/local/etc/v2ray/config.json | python3 -m json.tool > /dev/null && echo "OK"

重启 V2Ray 服务：

sudo systemctl restart v2ray
sudo systemctl status v2ray   # 确认 active (running)

客户端使用新 UUID 测试连接

预防措施：

安装 V2Ray 时注意官方脚本默认配置文件路径为 /usr/local/etc/v2ray/config.json
手动安装时若自定义 systemd 服务文件，需明确 -config 参数指定的路径
修改配置前先用 systemctl status v2ray 确认实际使用的配置文件位置
建议将所有配置统一存放在一个路径，避免混淆

相关命令速查：

# 查找所有可能的配置文件
find /etc /usr/local/etc -name "config.json" 2>/dev/null

# 对比文件差异
diff /etc/v2ray/config.json /usr/local/etc/v2ray/config.json

问题 15：3X-UI 面板无法访问

现象：

浏览器无法打开面板地址
连接超时

排查方向：

防火墙/安全组未放行端口

解决方案：

# 检查防火墙状态
ufw status

# 放行面板端口（如 54321）
ufw allow 54321/tcp

# 如果是云服务器，还需在安全组开放端口

问题 16：Xray 和手动 V2Ray 端口冲突

现象：

Failed to start: app/proxyman/inbound: failed to listen TCP on 443

原因：

3X-UI 自带 Xray 1.4.2，和手动安装的 V2Ray 同时占用 443 端口

解决方案：

方案一：停止手动的 V2Ray（推荐）

systemctl stop v2ray
systemctl disable v2ray
systemctl restart x-ui

方案二：给 Xray 分配不同端口

在 3X-UI 中将 WS+TLS 节点改为其他端口（如 8443）

附录一、配置实例（无域名方案）

1. 环境信息

项目	值
服务器	阿里云轻量应用服务器
系统	Ubuntu 22.04
公网 IP	（填入你的服务器IP）
V2Ray 版本	5.48.0

2. 两个节点信息

节点名称	端口	协议	UUID	传输方式
TCP 节点	10086	VLESS	`cat /proc/sys/kernel/random/uuid` 命令生成	TCP
WS+TLS 节点	443	VLESS	`cat /proc/sys/kernel/random/uuid` 命令生成	WebSocket + TLS

3. 客户端导入链接

TCP 节点：

vless://你的UUID@服务器IP:10086?encryption=none&type=tcp#VLESS-TCP

WS+TLS 节点：

vless://你的UUID@服务器IP:443?encryption=none&type=ws&path=/v2ray&security=tls&allowInsecure=true#VLESS-WS-TLS

4. 生成自签名证书

mkdir -p /etc/ssl/private /etc/ssl/certs

openssl req -x509 -nodes -newkey rsa:2048 \
  -keyout /etc/ssl/private/key.pem \
  -out /etc/ssl/certs/cert.pem \
  -subj "/CN=example.com" \
  -days 3650

# 修复目录权限（否则 systemd 无法读取）
chmod 755 /etc/ssl/private/

参考链接

Ollama 安装指南

Tue, 27 Jan 2026 19:17:35 +0800

在 Windows 系统上，Ollama 的安装位置可以通过命令行参数自定义，避免默认安装到 C 盘。以下是具体操作方法：

1、自定义 Ollama 安装路径

下载安装包：从 Ollama 官网下载 OllamaSetup.exe 安装包。
准备目标目录：创建一个你希望安装 Ollama 的目录，例如 D:\Ollama。
以管理员身份打开命令行：打开 PowerShell 或命令提示符（CMD），并切换到安装包所在目录。
执行安装命令：使用 /DIR 参数指定目标路径。例如，要将 Ollama 安装到 D:\Ollama，请运行以下命令：
```
    OllamaSetup.exe /DIR=D:\Ollama
```

2、自定义模型存储路径

Ollama 拉取的模型文件默认存储在用户目录下（如 C:\Users\<用户名>\.ollama\models），为节省 C 盘空间，建议同时修改模型存储路径：

创建模型存储目录：在目标磁盘上创建一个目录，例如 D:\AI\Models\Ollama。
设置环境变量：
- 按下 Win + R，输入 sysdm.cpl，打开“系统属性”。
- 点击“高级”选项卡下的“环境变量”。
- 在“系统变量”区域，点击“新建”。
- 变量名输入：OLLAMA_MODELS
- 变量值输入：你创建的模型存储路径，例如 D:\AI\Models\Ollama。
- 点击“确定”保存。
重启终端：关闭并重新打开命令行窗口，使环境变量生效。

本地部署 AI 大模型

Tue, 27 Jan 2026 16:23:34 +0800

DeepSeek 大模型本地部署指南（Ollama+Chatbox）

一、安装 Ollama

Windows 系统

访问 Ollama 官网下载安装包（约 100MB）
双击安装，默认路径为 C:\Program Files\Ollama，自动添加环境变量

验证安装：


ollama --version  # 输出版本号即成功

Linux 系统


curl -fsSL https://ollama.com/install.sh | sh  # 自动安装并启动服务
systemctl status ollama  # 检查服务状态

二、下载 DeepSeek 模型

7B 模型（流畅运行，推荐）


ollama pull deepseek-r1:7b

33B 模型（需量化，显存占用约 18GB）


ollama pull deepseek-coder:33b --quantize q4_0  # INT4 量化
# 拉取 q4 量化版本（推荐）
ollama pull deepseek-coder:33b-instruct-q4_K_M

1.5B 模型（低配设备适用）


ollama pull deepseek-r1:1.5b

验证下载


ollama list  # 显示已下载模型

三、启动模型并测试

命令行交互


ollama run deepseek-r1:7b  # 输入问题测试（如"写一首诗"）

API 调用（集成到项目）


import requests
response = requests.post(
    "http://localhost:11434/api/generate",
    json={"model": "deepseek-r1:7b", "prompt": "你好"}
)
print(response.json())

四、启动 Chatbox 并连接 Ollama

步骤1：下载 Chatbox

访问 Chatbox GitHub 仓库或 Chatbox 官网，下载对应系统的版本。

步骤2：配置 Ollama 连接

打开 Chatbox，进入设置界面；
在“模型提供方”中选择“Ollama”；
输入 Ollama 的 API 地址（默认为 http://localhost:11434）。

步骤3：选择模型并开始对话

在模型列表中选择已下载的 deepseek-r1:7b；
在输入框中输入问题（如“解释量子计算的基本原理”），点击发送。

五、进阶使用技巧

1. 自定义模型参数


ollama run deepseek-r1:7b --temperature 0.7 --top-p 0.9

--temperature：控制输出随机性（0-1，值越高越创意）；
--top-p：限制输出词汇的累积概率（0-1，值越低越保守）。

2. 批量处理任务

在 Chatbox 设置中启用“批量模式”；
将问题以换行符分隔的文本粘贴至输入框；
点击发送，系统将逐条回答并显示进度。

3. 模型微调（可选）

准备训练数据（格式为 JSONL，每行包含 prompt 和 response）；

执行微调命令：


ollama fine-tune deepseek-r1:7b --data training_data.jsonl

4. 进阶配置

多 GPU 支持

Linux：export CUDA_VISIBLE_DEVICES=0,1
Windows 命令提示符：set CUDA_VISIBLE_DEVICES=0,1

其他图形化界面

安装 Open WebUI，配置 API 地址为 http://localhost:11434

六、常见问题与解决方案

1. 模型下载失败

原因：网络不稳定或 Ollama 服务器繁忙；

解决：

使用代理工具加速下载；
尝试更换模型版本（如从 7b 换为 3b）；

手动下载模型文件（Linux 示例）：


wget https://huggingface.co/deepseek-ai/deepseek-r1-7b/resolve/main/ggml-model-q4_0.bin
ollama create deepseek-r1 -f Modelfile  # 自定义模型指向本地文件

2. 内存不足错误

现象：终端显示 out of memory；
解决：
1. 关闭其他占用内存的程序；
2. 降低模型参数（如换用 3b 版本）；
3. 在 Linux/macOS 下启用交换空间（swap）。

3. Chatbox 无法连接 Ollama

检查点：
1. 确认 Ollama 服务已启动（终端输入 ollama serve）；
2. 检查防火墙设置，允许 11434 端口的入站连接；
3. 重启 Chatbox 和 Ollama。

七、验证部署成功

1. 健康检查


curl http://localhost:11434  # 返回 {"version": "x.x.x", "features": ["models"]} 即正常

2. 性能测试

7B 模型响应延迟应低于 20ms；
33B 模型（量化后）响应延迟约 50ms；
测试长文本处理：输入 64K 上下文（如《三体》章节），检查摘要生成质量。

八、适用场景与扩展建议

1. 典型应用场景

教育领域：部署于学校实验室，供学生练习 AI 对话；
中小企业：快速搭建客服系统，降低外包成本；
个人开发者：测试模型性能，为项目提供原型支持。

2. 扩展方向

多模态支持：结合 Stable Diffusion 等工具，实现图文交互；
移动端适配：通过 Termux（Android）或 iSH（iOS）在手机上运行 Ollama；
企业级部署：使用 Docker 容器化 Ollama，实现集群化管理。

九、总结与行动建议

下载 Ollama 和 Chatbox，完成基础安装；
尝试运行 deepseek-r1:3b 或 deepseek-r1:7b 模型，体验基础对话功能；
根据需求调整参数或扩展功能（如批量处理、API 集成）。

本地化 AI 的未来，正从这一步开始！

注：文档部分内容由 AI 生成，实际操作以官方最新指南为准。

（注：文档部分内容可能由 AI 生成）

Videojs 使用 Hls 对视频加密解码

Thu, 18 Dec 2025 15:55:26 +0800

下载Hls.js

npm install hls.js

video 播放组件

<template>
  <div
    v-bind="$attrs"
    class="videoPlayer"
    ref="videoPlayerRef"
    v-loading="loading"
    element-loading-text="视频加载中"
    element-loading-spinner="el-icon-loading"
    element-loading-background="rgba(0, 0, 0, 0.8)"
  >
    <video class="video-js" ref="videoRef" :id="id" style="width: 100%; height: 100%;object-fit: cover;position: relative;" :poster="poster" controls></video>
  </div>
</template>

<script setup>
import { onMounted, onBeforeUnmount, watch, ref, nextTick } from 'vue'
import { getVideoUrl } from './index'
import { getToken } from '@/utils/auth'
import videojs from 'video.js'
import 'video.js/dist/video-js.css'
import 'videojs-flvjs-es6'
import 'videojs-flash'
import Hls from 'hls.js'

const overrideNative = ref(false)
const props = defineProps({
  videoId: { type: String, default: '' },
})
const loading = ref(false)
const videoRef = ref(null)
const poster = ref('')

const videoID = ref(props.videoId)

// ============================================================

let player

const initPlayer = () => {
  if (player) {
    player.dispose()
    player.value = null
  }
  try {
    player = videojs(videoRef.value, options(), playerReady)
  } catch (error) {}
}
const playerReady = () => {
  emit('playerMounted', player)

  // 强制显示大播放按钮 及其样式自定义
  player.bigPlayButton.show()
  player.bigPlayButton.el().style.display = 'block'
  player.bigPlayButton.el().style.opacity = '1'
  player.bigPlayButton.el().style.top = '50%'
  player.bigPlayButton.el().style.left = '50%'
  player.bigPlayButton.el().style.transform = 'translate(-50%, -50%)'
  player.bigPlayButton.el().style.borderRadius = '50%'

  // 添加自定义播放控制
  player.ready(() => {
    console.log('Video.js播放器准备就绪')
    loading.value = false
    
    // 监听视频可播放事件
    player.on('loadeddata', () => {
      console.log('视频已加载，可以播放')
      emit('videoCanplaythrough')
    })
    
    // 处理播放错误
    player.on('error', (e) => {
      console.error('播放错误:', player.error())
    })
  })
  // 大按钮点击事件（强制绑定）
  player.bigPlayButton.on('click', async () => {
    videoRef.value.play()
    player.bigPlayButton.hide()
    emit('videoPlay')
  })

  player.on('canplaythrough', function () {
    videojs.log('视频可以播放')
    emit('videoCanplaythrough')
  })
  player.on('play', function () {
    videojs.log('视频准备播放')
    // 此代码导致无法拉动长度，换用挂在完毕之后外侧处理
    player.currentTime(props.videoProgress)
    emit('videoPlay')
  })
  player.on('playing', function () {
    player.bigPlayButton.hide()
    videojs.log('视频已开始播放')
    emit('videoPlaying')
  })
  player.on('pause', function (event) {
    player.bigPlayButton.show()
    videojs.log('视频已暂停播放')
    emit('videoPause', event.target.player.cache_?.currentTime)
  })
  player.on('seeked', function (event) {
    emit('videoSeeked', event.target.player.cache_?.currentTime)
  })
  // 监听视频播放结束事件
  player.on('ended', function () {
    emit('videoEnded')
  })
  player.on('timeupdate', function () {
    var playedSeconds = player.currentTime() // 获取当前播放的秒数
    var duration = player.duration() // 获取视频总长度
    // 你可以在这里编写代码来处理视频播放进度
    emit('videoTimeupdate', playedSeconds)
  })
}

// =========================== 方法一 ====================================

// 获取加密地址与密钥
const getVideoInfo = async () => {
  loading.value = true
  getVideoUrl(videoID.value).then((res) => {
    poster.value = res.data.posterUrl ? res.data.posterUrl : ''
    if (Hls.isSupported()) {
        const hls = new Hls({
            debug: false,
            xhrSetup: function(xhr, url) {
                // 自定义密钥请求
                if (url.includes('/key/')) {
                    xhr.setRequestHeader('Authorization', 'Bearer ' + getToken());
                }
            }
        });
        hls.loadSource(res.data.m3u8Url);
        hls.attachMedia(videoRef.value);
        nextTick(() => {
          initPlayer() // 初始化播放器
          loading.value = false
        })
    } else if (videoRef.value.canPlayType('application/vnd.apple.mpegurl')) {
        // Safari原生支持
        videoRef.value.src = res.data.m3u8Url;
        player = videojs(videoRef.value, options());
        loading.value = false
    } else {
      console.log('您的浏览器不支持 HLS 播放')
    }
  })
}


// ======================================== 方法二 ==================================================
// const getVideoInfo = async () => {
//   loading.value = true
//   getVideoUrl(videoID.value).then((res) => {
//     poster.value = res.data.posterUrl ? res.data.posterUrl : ''
    
//     // 销毁现有播放器
//     if (player) {
//       player.dispose()
//       player = null
//     }
    
//     // 初始化Video.js播放器
//     player = videojs(videoRef.value, {
//       ...options(),
//       html5: {
//         hls: {
//           withCredentials: false,
//           // Video.js使用beforeRequest而不是xhrSetup
//           beforeRequest: function(options) {
            
//             // 判断是否是密钥请求
//             if (options.uri && options.uri.includes('/key/')) {
//               const token = getToken()
              
//               if (!token) {
//                 console.error('Token为空！')
//                 // 可以跳转到登录页或刷新token
//               }
              
//               // 添加Authorization头
//               options.headers = options.headers || {}
//               options.headers['Authorization'] = 'Bearer ' + token
//             }
//             return options
//           }
//         }
//       },
//       sources: [{
//         src: res.data.m3u8Url,
//         type: 'application/x-mpegURL'
//       }],
//       autoplay: false
//     })
    
//     // 监听播放器准备事件
//     playerReady()
//     player.ready(() => {
//     //   console.log('Video.js播放器准备就绪')
//     //   loading.value = false
      
//     //   // 监听错误事件
//     //   player.on('error', (e) => {
//     //     console.error('播放错误:', player.error())
        
//     //     // 如果是401错误，说明token有问题
//     //     const error = player.error()
//     //     if (error && error.code === 4) {
//     //       console.log('检测到权限错误(401)，可能是token过期')
//     //     }
//     //   })
      
//       // 监听网络请求
//       setupRequestInterceptor()
//     })
//   }).catch(error => {
//     console.error('获取视频信息失败:', error)
//     loading.value = false
//   })
// }

// const setupRequestInterceptor = () => {
//   // 方法1：拦截所有XMLHttpRequest
//   const originalXHROpen = XMLHttpRequest.prototype.open
//   const originalXHRSend = XMLHttpRequest.prototype.send
  
//   XMLHttpRequest.prototype.open = function(method, url) {
//     this._requestMethod = method
//     this._requestUrl = url
//     return originalXHROpen.apply(this, arguments)
//   }
  
//   XMLHttpRequest.prototype.send = function(body) {
//     // 拦截HLS相关请求
//     if (this._requestUrl && 
//         (this._requestUrl.includes('.m3u8') || 
//          this._requestUrl.includes('.ts') || 
//          this._requestUrl.includes('/key/'))) {
      
//       // console.log('拦截HLS请求:', this._requestUrl)
      
//       // 如果是密钥请求，添加token
//       if (this._requestUrl.includes('/key/')) {
//         const token = getToken()
//         // console.log('为密钥请求手动添加token')
//         this.setRequestHeader('Authorization', 'Bearer ' + token)
//       }
      
//       // 监听请求状态
//       this.addEventListener('readystatechange', function() {
//         if (this.readyState === 4) {
//           // console.log('HLS请求完成:', {
//           //   url: this._requestUrl,
//           //   status: this.status,
//           //   statusText: this.statusText
//           // })
          
//           if (this.status === 401) {
//             console.error('权限验证失败(401)，token可能无效')
//           }
//         }
//       })
//     }
    
//     return originalXHRSend.apply(this, arguments)
//   }
// }

watch(() => props.videoId, (newVal) => {
  if(!newVal) return
  getVideoInfo()
}, { immediate: true, deep: true })

const emit = defineEmits([
  // 播放器挂载完毕
  'playerMounted',
  'videoCanplaythrough',
  'videoPlay',
  'videoPlaying',
  'videoPause',
  'videoSeeked',
  'videoEnded',
  'videoTimeupdate'
])
// VideoJs更多选项配置可以参考中文文档：
function options() {
  return {
    html5: {
      hls: {
        overrideNative: overrideNative
      },
      nativeVideoTracks: !overrideNative,
      nativeAudioTracks: !overrideNative,
      nativeTextTracks: !overrideNative
    },
    autoplay: false, // true,浏览器准备好时开始播放。
    muted: true, // 默认情况下将会消除音频。
    loop: false, // 导致视频一结束就重新开始。
    controls: true,
    preload: 'auto', // auto浏览器选择最佳行为,立即开始加载视频（如果浏览器支持）
    fluid: true, // 当true时，将按比例缩放以适应其容器。
    type: 'application/x-mpegURl',
    notSupportedMessage: '此视频暂无法播放，请稍后再试', // 无法播放媒体源时显示的默认信息。
    textTrackDisplay: false,
    playbackRates: [0.5, 1, 1.5, 2], //倍速
  }
}

onBeforeUnmount(() => {
  if (player) {
    player.dispose()
    player = null
  }
})


</script>
<!-- scoped -->
<style lang="scss">
.videoPlayer {
  width: 100%;
  height: 100%;
  position: relative;
  overflow: hidden;  
}

.video-js {
  padding-top: 0 !important;
}
.video-js .vjs-time-control {
  display: block;
}
.video-js .vjs-remaining-time {
  display: none;
}
.vjs-playback-rate .vjs-playback-rate-value {
  font-size: 1em;
  line-height: 3em;
}
.vjs-poster {
  background-color: #00000000;
}
.video-js:hover .vjs-big-play-button{
  background-color: transparent;
  opacity: 1;
}
.video-js .vjs-big-play-button{
  background: transparent;
  width: 2em;
  height: 2em;
  font-size: 10em;
  background: rgba(0,0,0,0.1) url(./play.png) center / 100% 100% no-repeat !important;
  border: 0;
  border-radius: 50%;
  .vjs-icon-placeholder{
    display: none;
  }
}
</style>

方法一中点击视频元素无法进行播放，只能点击播放按钮；方法二中所有元素都可点击控制播放

// decode.vue
<template>
  <div class="content_box">
    <div class="wrapper">
      <div class="news-detail-title">
        {{ title }}
      </div>
      <div class="news-detail-content">
        <VideoPlayer
          v-if="videoID"
          :videoId="videoID"
          style="width: 100%; height: 500px"
        />
      </div>
    </div>
  </div>
</template>
<script setup>
import { getVideoInfo } from './index.js'
import VideoPlayer from '@/components/DecodeVideo/index.vue'

const route = useRoute()
const title = ref('')
const videoID = ref('')

const getVideoData = (id) => {
  getVideoInfo(id).then((res) => {
    title.value = res.data.title
    videoID.value = res.data.videoId
  })
}

onMounted(() => {
  // 新版解码
  getVideoData(route.query.id)
})
</script>

<style lang="scss" scoped>
.content_box {
  width: 100%;
  height: 100%;
  background: #f1f4f9;
  padding: 20px 0px;
  box-sizing: border-box;

  .wrapper {
    background-color: #fff;
    padding: 20px;
    box-sizing: border-box;

    .news-detail-title {
      text-align: center;
      color: #0043b2;
      font-size: 30px;
      font-weight: bold;
      margin: 10px 85px;
    }

    .news-detail-post {
      text-align: center;
      margin: 0 120px;
      color: #999;
      height: 60px;
      line-height: 60px;
      border-bottom: 1px solid #999;
      font-size: 12px;

      span {
        margin-right: 10px;
      }
    }

    .news-detail-content {
      padding: 10px 50px;
      min-height: calc(100vh - 122px - 48px - 330px);
      margin: 0 80px;
      line-height: 36px;
    }
  }
}
</style>

接口文件

import request from '@/utils/request'

export function getVideoKey(videoId) {
  return request({
    url: `/client/encrypted/video/key/${videoId}`,
    method: 'get',
    headers: {
      'Content-Type': 'application/octet-stream'
    }
  })
}

export function getVideoUrl(videoId) {
  return request({
    url: `/client/encrypted/video/playUrl/${videoId}`,
    method: 'get',
  })
}

Vue3 + VueOffice 全家桶进行多格式文件预览

Tue, 25 Nov 2025 15:04:43 +0800

vue-office

1Vue-Office预览的vue组件库，支持vue2/3。也支持非Vue框架的预览。

准备工作

#docx文档预览组件
npm install @vue-office/docx vue-demi@0.14.6

#excel文档预览组件
npm install @vue-office/excel vue-demi@0.14.6

#pdf文档预览组件
npm install @vue-office/pdf vue-demi@0.14.6

#pptx文档预览组件
npm install @vue-office/pptx vue-demi@0.14.6

如果是vue2.6版本或以下还需要额外安装 @vue/composition-api

npm install @vue/composition-api

组件代码如下

<template>
  <div
    class="office-viewer"
    :class="{ dragging: isDragging, zoomable: zoomLevel > 1 }"
    @wheel="handleWheel"
    @mousedown="handleMouseDown"
    @mousemove="handleMouseMove"
    @mouseup="handleMouseUp"
    @mouseleave="handleMouseLeave"
    ref="viewerContainer"
  >
    <!-- PDF预览 -->
    <VueOfficePdf
      v-if="trimmedType === 'pdf'"
      ref="pdfViewer"
      :src="encodedSrc"
      :style="{
        height: height,
        width: width,
      }"
      @rendered="onRendered"
      @error="onError"
    />

    <!-- Word文档预览 -->
    <VueOfficeDocx
      v-else-if="trimmedType === 'word'"
      ref="docxViewer"
      :src="encodedSrc"
      :style="{
        height: height,
        width: width,
      }"
      @rendered="onRendered"
      @error="onError"
    />

    <!-- Excel文档预览 -->
    <VueOfficeExcel
      v-else-if="trimmedType === 'excel'"
      ref="excelViewer"
      :src="encodedSrc"
      :style="{
        height: height,
        width: width,
      }"
      @rendered="onRendered"
      @error="onError"
    />

    <!-- PPT预览 -->
    <VueOfficePptx
      v-else-if="trimmedType === 'ppt'"
      ref="pptxViewer"
      :src="encodedSrc"
      :options="pptxOptions"
      :style="{
        height: height,
        width: width,
        transformOrigin: 'top left',
      }"
      @rendered="onPptxRendered"
      @error="onPptxError"
    />

    <!-- 视频、图片预览 -->
    <div class="img_video_box" v-else-if="trimmedType === 'video' || trimmedType === 'img'">
        <!-- 视频预览 -->
        <video
            v-if="trimmedType === 'video'"
            :src="encodedSrc"
            :style="{ height: height, width: width }"
            controls
        />
        <!-- 图片预览 -->
        <img
            v-if="trimmedType === 'img'"
            :src="encodedSrc"
            :style="{ height: height, width: width / 2 }"
        />
    </div>

    <!-- 不支持的文件类型 -->
    <div v-else class="unsupported-type">
      <div class="error-message">
        <i class="el-icon-warning"></i>
        <p>不支持的文件类型: {{ type }}</p>
        <p>支持的格式: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX</p>
      </div>
    </div>

    <!-- 加载状态 -->
    <div v-if="loading" class="loading-overlay">
      <div class="loading-spinner">
        <el-icon class="el-icon-loading"><Loading /></el-icon>
        <p>文档加载中...</p>
      </div>
    </div>

    <!-- 错误状态 -->
    <div v-if="error" class="error-overlay">
      <div class="error-message">
        <i class="el-icon-warning"></i>
        <p>文档加载失败</p>
        <p>{{ errorMessage }}</p>
        <button @click="retry" class="retry-btn">重试</button>
      </div>
    </div>

    <!-- 缩放控制提示 -->
    <div v-if="showZoomTip" class="zoom-tip">
      <span>缩放: {{ Math.round(zoomLevel * 100) }}%</span>
      <small>Ctrl+滚轮缩放，拖拽移动，双击重置</small>
    </div>

    <!-- 关闭按钮 -->
    <div class="close-btn" @click="emit('close')" title="关闭">
      <el-icon><Close /></el-icon>
    </div>
  </div>
</template>

<script setup>
import { ref, computed, watch, onMounted, readonly, nextTick } from "vue";
//引入VueOfficeDocx组件
import VueOfficeDocx from "@vue-office/docx";
//引入相关样式
import "@vue-office/docx/lib/index.css";
//引入VueOfficeExcel组件
import VueOfficeExcel from "@vue-office/excel";
//引入相关样式
import "@vue-office/excel/lib/index.css";
//引入VueOfficePdf组件
import VueOfficePdf from "@vue-office/pdf";
import VueOfficePptx from "@vue-office/pptx";

// 定义组件属性
const props = defineProps({
  // 文件类型: pdf, docx, doc, xlsx, xls, ppt, pptx
  type: {
    type: String,
    required: true,
    validator: (value) =>
      ["pdf", "word", "excel", "ppt", "video", "img"].includes(
        value.toLowerCase()
      ),
  },
  // 文件源地址
  src: {
    type: String,
    required: true,
  },
  // 容器高度
  height: {
    type: String,
    default: "100%",
  },
  // 容器宽度
  width: {
    type: String,
    default: "100%",
  },
  file: {
    type: Object,
    default: () => ({
        type: '',
        src: '',
    }),
  }
});

// 定义事件
const emit = defineEmits(["rendered", "error", "loading", "close"]);

// 响应式数据
const loading = ref(false);
const error = ref(false);
const errorMessage = ref("");
const zoomLevel = ref(1);
const showZoomTip = ref(false);
const viewerContainer = ref(null);
const pdfViewer = ref(null);
const docxViewer = ref(null);
const excelViewer = ref(null);
const pptxViewer = ref(null);
let zoomTipTimer = null;

// 拖拽相关状态
const isDragging = ref(false);
const dragStart = ref({ x: 0, y: 0 });
const dragOffset = ref({ x: 0, y: 0 });
const lastDragOffset = ref({ x: 0, y: 0 });

// 支持的文件类型
const supportedTypes = ["pdf", "word", "excel", "ppt", "video", "img"];

// PPTX配置选项
const pptxOptions = ref({
  // 启用图片渲染
  enableImages: true,
  // 设置渲染模式
  renderMode: "canvas",
  // 缩放比例
  scale: 1,
  // 启用调试模式
  debug: true,
});

// 处理去除空格的文件类型
const trimmedType = computed(() => {
  return props.type.trim().toLowerCase();
});

// 检查文件类型是否支持
const isSupported = computed(() => {
  return supportedTypes.includes(trimmedType.value);
});

// 对src进行URL编码
const encodedSrc = computed(() => {
  return props.src;
});

// 文档渲染完成回调
const onRendered = () => {
  loading.value = false;
  error.value = false;
  emit("rendered");
};

// 文档加载错误回调
const onError = (err) => {
  loading.value = false;
  error.value = true;
  errorMessage.value = err.message || "文档加载失败";
  emit("error", err);
};

// PPTX文档渲染完成回调
const onPptxRendered = () => {
  console.log("PPTX文档渲染完成");
  console.log("当前src:", encodedSrc.value);
  console.log("文档类型:", trimmedType.value);
  loading.value = false;
  error.value = false;
  emit("rendered");
};

// PPTX文档加载错误回调
const onPptxError = (err) => {
  console.error("PPTX文档渲染失败:", err);
  console.log("失败时的src:", encodedSrc.value);
  console.log("失败时的文档类型:", trimmedType.value);
  loading.value = false;
  error.value = true;
  errorMessage.value = err.message || "PPTX文档加载失败";
  emit("error", err);
};

// 重试加载
const retry = () => {
  error.value = false;
  errorMessage.value = "";
  loading.value = true;
};

// 处理鼠标滚轮缩放（需要按住Ctrl键）
const handleWheel = (event) => {
  // 只有按住Ctrl键时才进行缩放
  if (!event.ctrlKey) {
    return;
  }
  event.preventDefault();
  if(props.type == 'img' || props.type == 'video' || props.type == 'other') return

  

  const delta = event.deltaY > 0 ? -0.1 : 0.1;
  const newZoomLevel = Math.max(0.5, Math.min(3, zoomLevel.value + delta));

  zoomLevel.value = newZoomLevel;

  // 显示缩放提示
    showZoomTip.value = true

  // 清除之前的定时器
  if (zoomTipTimer) {
    clearTimeout(zoomTipTimer);
  }

  // 2秒后隐藏提示
  zoomTipTimer = setTimeout(() => {
    showZoomTip.value = false;
  }, 2000);
};

// 双击重置缩放
const handleDoubleClick = () => {
  zoomLevel.value = 1;
  dragOffset.value = { x: 0, y: 0 };
  lastDragOffset.value = { x: 0, y: 0 };
  showZoomTip.value = true;

  if (zoomTipTimer) {
    clearTimeout(zoomTipTimer);
  }

  zoomTipTimer = setTimeout(() => {
    showZoomTip.value = false;
  }, 1000);
};

// 重置缩放级别
const resetZoom = () => {
  zoomLevel.value = 1;
  // 重置拖拽偏移
  dragOffset.value = { x: 0, y: 0 };
  lastDragOffset.value = { x: 0, y: 0 };
};

// 重置vue-office组件内部滚动位置
const resetOfficeViewerScroll = () => {
  // 使用nextTick确保组件已经渲染
  nextTick(() => {
    // 重置PDF组件滚动位置
    if (pdfViewer.value && pdfViewer.value.$el) {
      const pdfContainer =
        pdfViewer.value.$el.querySelector(".pdf-viewer") || pdfViewer.value.$el;
      if (pdfContainer) {
        pdfContainer.scrollTop = 0;
      }
    }

    // 重置Word组件滚动位置
    if (docxViewer.value && docxViewer.value.$el) {
      const docxContainer =
        docxViewer.value.$el.querySelector(".docx-viewer") ||
        docxViewer.value.$el;
      if (docxContainer) {
        docxContainer.scrollTop = 0;
      }
    }

    // 重置Excel组件滚动位置
    if (excelViewer.value && excelViewer.value.$el) {
      const excelContainer =
        excelViewer.value.$el.querySelector(".excel-viewer") ||
        excelViewer.value.$el;
      if (excelContainer) {
        excelContainer.scrollTop = 0;
      }
    }

    // 重置PPT组件滚动位置
    if (pptxViewer.value && pptxViewer.value.$el) {
      const pptxContainer =
        pptxViewer.value.$el.querySelector(".pptx-viewer") ||
        pptxViewer.value.$el;
      if (pptxContainer) {
        pptxContainer.scrollTop = 0;
      }
    }
  });
};

// 处理鼠标按下事件（开始拖拽）
const handleMouseDown = (event) => {
  if (zoomLevel.value > 1) {
    isDragging.value = true;
    dragStart.value = {
      x: event.clientX - dragOffset.value.x,
      y: event.clientY - dragOffset.value.y,
    };
    event.preventDefault();
  }
};

// 处理鼠标移动事件（拖拽中）
const handleMouseMove = (event) => {
  if (isDragging.value && zoomLevel.value > 1) {
    dragOffset.value = {
      x: event.clientX - dragStart.value.x,
      y: event.clientY - dragStart.value.y,
    };
    event.preventDefault();
  }
};

// 处理鼠标释放事件（结束拖拽）
const handleMouseUp = () => {
  if (isDragging.value) {
    isDragging.value = false;
    lastDragOffset.value = { ...dragOffset.value };
  }
};

// 处理鼠标离开事件
const handleMouseLeave = () => {
  if (isDragging.value) {
    isDragging.value = false;
    lastDragOffset.value = { ...dragOffset.value };
  }
};

// 监听src变化，重新加载文档
watch(
  () => props.src,
  (newSrc) => {
    if (newSrc) {
      loading.value = true;
      error.value = false;
      errorMessage.value = "";
      // 重置滚动位置到顶部
      if (viewerContainer.value) {
        viewerContainer.value.scrollTop = 0;
      }
      // 重置vue-office组件内部滚动位置
      resetOfficeViewerScroll();
    }
  },
  { immediate: true }
);

// 监听type变化
watch(
  () => props.type,
  (newType) => {
    if (newType && props.src) {
      loading.value = true;
      error.value = false;
      errorMessage.value = "";
    }
  }
);

// 组件挂载时初始化
onMounted(() => {
  if (props.src && isSupported.value) {
    loading.value = true;
  } else {
    loading.value = false;
  }
  if(props.type == 'img' || props.type == 'video'){
    nextTick(() => {
        loading.value = false
    })
  }

  // 添加双击事件监听
  if (viewerContainer.value) {
    viewerContainer.value.addEventListener("dblclick", handleDoubleClick);
  }
});

// 暴露方法供外部调用
defineExpose({
  resetZoom,
  resetOfficeViewerScroll,
  zoomLevel: readonly(zoomLevel),
  handleMouseDown,
  handleMouseMove,
  handleMouseUp,
  handleMouseLeave,
  onPptxRendered,
  onPptxError,
  pptxOptions,
});

const getTransform = computed(() => {
    if(props.type == 'excel' || props.type == 'ppt') {
        zoomLevel.value = 0.8
    }
    return `scale(${zoomLevel.value}) translate(${dragOffset.value.x}px, ${dragOffset.value.y}px)`
})
</script>

<style lang="scss" scoped>
.office-viewer {
  position: relative;
  width: 100%;
  height: 100%;
  background: transparent;
  border-radius: 4px;
  overflow: hidden;
  box-sizing: border-box;
  cursor: grab;
  user-select: none;
  overflow-y: auto;
  scrollbar-width: none;
  &:active {
    cursor: grabbing;
  }

  &.dragging {
    cursor: grabbing;
  }

  &.zoomable {
    cursor: grab;

    &:hover {
      cursor: grab;
    }
  }

  &:not(.zoomable) {
    cursor: default;
  }

  // 确保所有子元素都使用border-box
  * {
    box-sizing: border-box;
  }

  .img_video_box{
    width: 100%;
    height: 100%;
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 20px;
    background: rgba(0, 0, 0, .5);
  }

  // 缩放提示样式
  .zoom-tip {
    position: absolute;
    top: 20px;
    right: 20px;
    background: rgba(0, 0, 0, 0.8);
    color: white;
    padding: 8px 12px;
    border-radius: 4px;
    font-size: 12px;
    z-index: 1001;
    pointer-events: none;
    transition: opacity 0.3s ease;

    span {
      display: block;
      font-weight: 500;
      margin-bottom: 2px;
    }

    small {
      opacity: 0.8;
      font-size: 10px;
    }
  }

  // 加载状态样式
  .loading-overlay {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background: transparent !important;
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 1000;

    .loading-spinner {
      text-align: center;
      color: #409eff;

      i {
        font-size: 32px;
        margin-bottom: 10px;
        animation: rotate 2s linear infinite;
      }

      p {
        margin: 0;
        font-size: 14px;
        letter-spacing: 5px;
        color: #f7f8fb;
      }
    }
  }

  // 错误状态样式
  .error-overlay {
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background: transparent !important;
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 1000;

    .error-message {
      text-align: center;
      color: #f56c6c;

      i {
        font-size: 48px;
        margin-bottom: 16px;
        display: block;
      }

      p {
        margin: 8px 0;
        font-size: 14px;
        color: #f7f8fb;

        &:first-of-type {
          font-size: 16px;
          font-weight: 500;
          color: #f56c6c;
        }
      }

      .retry-btn {
        margin-top: 16px;
        padding: 8px 16px;
        background: #409eff;
        color: white;
        border: none;
        border-radius: 4px;
        cursor: pointer;
        font-size: 14px;
        transition: background-color 0.3s;

        &:hover {
          background: #66b1ff;
        }
      }
    }
  }

  // 不支持的文件类型样式
  .unsupported-type {
    height: 100%;
    display: flex;
    align-items: center;
    justify-content: center;
    background: rgba(0, 0, 0, .5);

    .error-message {
      text-align: center;
      color: #e6a23c;

      i {
        font-size: 48px;
        margin-bottom: 16px;
        display: block;
      }

      p {
        margin: 8px 0;
        font-size: 14px;
        color: rgb(241, 241, 241, .7);

        &:first-of-type {
          font-size: 16px;
          font-weight: 500;
          color: #e6a23c;
        }
      }
    }
  }

  .close-btn{
    position: absolute;
    top: 20px;
    left: 20px;
    width: 40px;
    height: 40px;
    display: flex;
    align-items: center;
    justify-content: center;
    background: rgba(0, 0, 0, 0.5);
    color: white;
    border-radius: 50%;
    font-size: 20px;
    z-index: 1001;
    transition: all 0.2s linear;
    cursor: pointer;
  }
  .close-btn:hover{
    background: rgba(0, 0, 0, 0.3);
  }
}

// 旋转动画
@keyframes rotate {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

// pdf
::v-deep .vue-office-pdf-wrapper{
  background: transparent !important;
  scrollbar-width: none !important;
  padding: 20px !important;
  transform: v-bind(getTransform);
}
:deep(.vue-office-pdf) {
  background: rgba(0, 0, 0, .5) !important;
}

// excel
:deep(.vue-office-excel) {
  padding: 20px !important;
  background: rgba(0, 0, 0, .5) !important;
  scrollbar-width: none !important;
}
:deep(.vue-office-excel-main){
    width: 100% !important;
    height: 100% !important;
    overflow: auto !important;
    transform: v-bind(getTransform);
}

// word
:deep(.vue-office-docx) {
  width: 100% !important;
  height: 100% !important;
  background: rgba(0, 0, 0, .5) !important;
}
:deep(.docx-wrapper) {
 background: transparent !important;
 padding: 20px !important;
 transform: v-bind(getTransform);
}

// ppt 
::v-deep .vue-office-pptx{
  scrollbar-width: none !important;
  padding: 20px !important;
  scrollbar-width: none !important;
  background: rgba(0, 0, 0, .5) !important;
}
:deep(.pptx-preview-wrapper){
    transform: v-bind(getTransform);
    background: transparent !important;
}
</style>

从文件名中提取文件类型后缀

Fri, 21 Nov 2025 10:18:18 +0800

代码

/**
 * 从文件名中提取文件类型后缀
 * @param {string} fileName - 文件名（含后缀）
 * @returns {string} - 文件后缀（小写，无`.`；若无后缀返回空字符串）
 */
function getFileExtension(fileName) {
  // 校验参数：非字符串或空字符串直接返回空
  if (typeof fileName !== 'string' || fileName.trim() === '') {
    return '';
  }

  // 找到最后一个点的索引
  const lastDotIndex = fileName.lastIndexOf('.');
  // 处理特殊情况：点在开头（如`.gitignore`）或无点，返回空
  if (lastDotIndex === -1 || lastDotIndex === 0) {
    return '';
  }

  // 截取后缀并转为小写（统一格式，避免PNG/png混用）
  const extension = fileName.slice(lastDotIndex + 1).toLowerCase();
  return extension;
}

测试

// 测试示例
const fileName = '3d49ffb0-ba4f-43ae-9b08-8aa9411db43d.png';
const extension = getFileExtension(fileName);
console.log('文件后缀：', extension); // 输出：png

// 更多测试用例
console.log(getFileExtension('document.pdf')); // pdf
console.log(getFileExtension('image.tar.gz')); // gz（处理多后缀，取最后一个）
console.log(getFileExtension('.env')); // 空（点在开头）
console.log(getFileExtension('无后缀文件')); // 空
console.log(getFileExtension('file.name.with.many.dots.jpg')); // jpg

免费API

Fri, 14 Nov 2025 10:24:22 +0800

获取图片
700 : 宽度；400高度
https://loremflickr.com/700/400

/**
    * 将 Base64 字符串转换为 Blob 对象
    * @param {string} base64String - 完整的 Base64 字符串（含前缀）
    * @param {string} mimeType - 文件类型（如 'image/png'，可选，默认从 Base64 前缀提取）
    * @returns {Blob} 转换后的 Blob 对象
    */
    base64ToBlob(base64String, mimeType) {
      // 提取 Base64 数据部分（去除前缀）
      const base64Data = base64String.split(',')[1];
      // 解码 Base64 为二进制字符串
      const byteCharacters = atob(base64Data);
      // 转换为 Uint8Array 二进制数组
      const byteNumbers = new Array(byteCharacters.length);
      for (let i = 0; i < byteCharacters.length; i++) {
        byteNumbers[i] = byteCharacters.charCodeAt(i);
      }
      const byteArray = new Uint8Array(byteNumbers);

      // 确定 MIME 类型（优先使用传入的，否则从 Base64 前缀提取）
      const type = mimeType || base64String.split(';')[0].split(':')[1];
      
      // 生成 Blob 对象（可直接作为文件使用）
      return new Blob([byteArray], { type });
    },

Canvas 绘制荣誉证书等（下载、自定义）

Fri, 14 Nov 2025 08:35:48 +0800

代码

/**
 * Canvas图片生成器类（增强版）
 * 支持百分比坐标、元素宽度控制、CSS样式配置和高级文本布局
 * 支持多个内容模块循环渲染，类似Vue插槽的默认配置机制
 */
/**
 * Canvas图片生成器类（增强版）
 * 支持基于文本精确高度的自动定位
 */
class CanvasImageGenerator {
    /**
     * 构造函数
     * @param {Object} options 配置选项
     */
    constructor(options) {
        // 默认配置
        options = options || {};
        this.config = {
            width: 800,
            height: 500,
            backgroundColor: '#3498db',
            backgroundPadding: 0 // 背景图片内边距
        };
        // 合并选项
        if (options.width !== undefined) this.config.width = options.width;
        if (options.height !== undefined) this.config.height = options.height;
        if (options.backgroundColor !== undefined) this.config.backgroundColor = options.backgroundColor;
        if (options.backgroundPadding !== undefined) this.config.backgroundPadding = options.backgroundPadding;
        
        // 创建Canvas元素
        this.canvas = document.createElement('canvas');
        this.canvas.width = this.config.width;
        this.canvas.height = this.config.height;
        this.ctx = this.canvas.getContext('2d');
        
        // 文字元素默认配置模板
        this.elementTemplates = {
            title: {
                text: '结业证书',
                fontFamily: 'Arial, "Microsoft YaHei", sans-serif',
                fontSize: 32,
                color: '#ff6b6b',
                x: '10%',
                y: '28%',
                width: '80%',
                bold: true,
                italic: false,
                shadow: false,
                textAlign: 'center',
                textBaseline: 'middle',
                overflow: 'wrap',
                lineHeight: 1.2,
                padding: 0,
                maxLines: 0,
                whiteSpace: 'normal',
                textIndent: 0,
                letterSpacing: 0,
                wordSpacing: '50px',
                textAlignLast: 'start',
                enabled: true
            },
            content: {
                text: '请在此处填写证书内容...',
                fontFamily: 'Arial, "SimSun", sans-serif',
                fontSize: 18,
                color: '#333',
                x: '15%',
                y: '33%',
                width: '70%',
                bold: false,
                italic: false,
                shadow: false,
                textAlign: 'justify',
                textBaseline: 'top',
                overflow: 'wrap',
                lineHeight: 1.5,
                padding: 0,
                maxLines: 0,
                whiteSpace: 'normal',
                textIndent: 36,
                letterSpacing: 0,
                wordSpacing: 0,
                textAlignLast: 'start',
                enabled: true,
                autoPosition: true // 默认启用自动定位
            },
            date: {
                text: '2023年1月1日',
                fontFamily: 'Arial, "Microsoft YaHei", sans-serif',
                fontSize: 14,
                color: '#666',
                x: '60%',
                y: '80%',
                width: '40%',
                bold: false,
                italic: false,
                shadow: false,
                textAlign: 'left',
                textBaseline: 'middle',
                overflow: 'ellipsis',
                lineHeight: 1.2,
                padding: 0,
                maxLines: 1,
                whiteSpace: 'nowrap',
                textIndent: 0,
                letterSpacing: 0,
                wordSpacing: 0,
                textAlignLast: 'start',
                enabled: true
            },
            unit: {
                text: '某某机构',
                fontFamily: 'Arial, "Microsoft YaHei", sans-serif',
                fontSize: 14,
                color: '#666',
                x: '60%',
                y: '75%',
                width: '40%',
                bold: false,
                italic: false,
                shadow: false,
                textAlign: 'left',
                textBaseline: 'middle',
                overflow: 'ellipsis',
                lineHeight: 1.2,
                padding: 0,
                maxLines: 1,
                whiteSpace: 'nowrap',
                textIndent: 0,
                letterSpacing: 0,
                wordSpacing: 0,
                textAlignLast: 'start',
                enabled: true
            },
            certificateNo: {
                text: 'NO.20230001',
                fontFamily: 'Arial, "Microsoft YaHei", sans-serif',
                fontSize: 14,
                color: '#666',
                x: '17%',
                y: '80%',
                width: '50%',
                bold: false,
                italic: false,
                shadow: false,
                textAlign: 'left',
                textBaseline: 'middle',
                overflow: 'ellipsis',
                lineHeight: 1.2,
                padding: 0,
                maxLines: 1,
                whiteSpace: 'nowrap',
                textIndent: 0,
                letterSpacing: 1,
                wordSpacing: 0,
                textAlignLast: 'start',
                enabled: true
            }
        };

        // 当前激活的元素配置
        this.elements = {};
        
        // 文本测量缓存
        this._textWidthCache = new Map();
        // 字体特性缓存
        this._fontMetricsCache = new Map();
    }
    
    /**
     * 生成图片（支持多个内容模块）
     * @param {Object} params 生成参数
     * @returns {Promise<string>} 图片DataURL
     */
    async generate(params) {
        try {
            // 合并参数
            params = params || {};
            const background = params.background;
            const title = params.title;
            const content = params.content;
            const date = params.date;
            const unit = params.unit;
            const certificateNo = params.certificateNo;
            const contents = params.contents || [];
            
            // 更新配置
            if (params.width) this.config.width = params.width;
            if (params.height) this.config.height = params.height;
            if (params.backgroundColor) this.config.backgroundColor = params.backgroundColor;
            if (params.backgroundPadding !== undefined) this.config.backgroundPadding = params.backgroundPadding;
            
            // 更新Canvas尺寸
            this.canvas.width = this.config.width;
            this.canvas.height = this.config.height;
            
            // 重置元素配置
            this.elements = {};
            
            // 处理单个元素配置
            if (title) this.addElement('title', title);
            if (content) this.addElement('content', content);
            if (date) this.addElement('date', date);
            if (unit) this.addElement('unit', unit);
            if (certificateNo) this.addElement('certificateNo', certificateNo);
            
            // 处理多个内容模块（核心改进：基于精确高度的自动定位）
            if (contents && contents.length > 0) {
                this.processMultipleContents(contents);
            }
            
            // 绘制
            await this.drawBackground(background);
            this.drawAllElements();
            
            return this.canvas.toDataURL('image/png');
        } catch (error) {
            console.error('生成图片时出错:', error);
            throw error;
        }
    }
    
    /**
     * 处理多个内容模块（基于内容高度的智能定位）
     * @param {Array} contents 内容模块数组
     */
    processMultipleContents(contents) {
        // 计算起始Y位置（考虑顶部内容的高度）
        let currentY = this.calculateInitialYPosition();
        
        contents.forEach((contentConfig, index) => {
            const elementKey = `content_${index}`;
            
            // 合并默认配置和自定义配置
            const mergedConfig = this.mergeWithTemplate('content', contentConfig);
            
            // 仅对启用自动定位的模块进行位置计算
            if (mergedConfig.autoPosition) {
                // 设置当前内容模块的位置为当前Y坐标
                mergedConfig.y = `${currentY}%`;
                
                // 计算当前内容模块的精确高度
                const contentHeight = this.calculateExactContentHeight(mergedConfig);
                
                // 累加当前模块高度和间距作为下一个模块的起始位置
                currentY += contentHeight + 3; // 3% 的间距
                console.log(`内容模块${index + 1} - Y位置: ${mergedConfig.y}, 高度: ${contentHeight}%, 下一模块起始Y: ${currentY}%`);
            } else {
                // 不启用自动定位时，保持原有Y坐标，但仍需计算其高度用于后续模块
                const contentHeight = this.calculateExactContentHeight(mergedConfig);
                currentY = parseFloat(mergedConfig.y) + contentHeight + 3;
                console.log(`内容模块${index + 1} (不自动定位) - Y位置: ${mergedConfig.y}, 高度: ${contentHeight}%, 下一模块起始Y: ${currentY}%`);
            }
            
            this.elements[elementKey] = mergedConfig;
        });
    }
    
    /**
     * 计算初始Y位置（考虑标题等顶部元素的高度）
     * @returns {number} 初始Y位置百分比
     */
    calculateInitialYPosition() {
        // 如果有标题元素，从标题下方开始
        if (this.elements.title && this.elements.title.enabled) {
            const titleHeight = this.calculateExactContentHeight(this.elements.title);
            const titleY = parseFloat(this.elements.title.y);
            return titleY + titleHeight + 3; // 标题Y坐标 + 标题高度 + 3%间距
        }
        return 35; // 默认起始位置
    }
    
    /**
     * 计算内容模块的精确高度（修复首行缩进和高度计算问题）
     * @param {Object} config 内容配置
     * @returns {number} 高度百分比
     */
    calculateExactContentHeight(config) {
        // 保存当前字体设置
        const originalFont = this.ctx.font;
        
        // 设置当前配置的字体
        let fontStyle = '';
        if (config.bold) fontStyle += 'bold ';
        if (config.italic) fontStyle += 'italic ';
        const font = `${fontStyle}${config.fontSize}px ${config.fontFamily}`;
        this.ctx.font = font;
        
        // 获取字体度量信息
        const fontMetrics = this.getFontMetrics(font, config.fontSize);
        
        const {
            text,
            lineHeight,
            maxLines,
            width,
            padding,
            textIndent,
            whiteSpace,
            overflow
        } = config;
        
        // 计算实际内容宽度（像素）
        const contentWidth = this.parseValueToPixel(width, 'width') - (padding || 0) * 2;
        
        // 关键修复：计算实际可用宽度时考虑首行缩进
        let firstLineMaxWidth = contentWidth;
        if (textIndent > 0) {
            firstLineMaxWidth = contentWidth - textIndent;
        }
        
        // 分割文本行（使用优化后的分割方法）
        let lines = [];
        let isEllipsisOrClip = overflow === 'ellipsis' || overflow === 'clip';
        
        if (whiteSpace === 'nowrap' || isEllipsisOrClip) {
            // 不换行、省略号或裁剪模式 - 只处理一行
            lines = [text];
        } else {
            // 按段落分割并使用严格换行逻辑
            const paragraphs = text.split('\n');
            paragraphs.forEach((paragraph, paraIndex) => {
                if (paragraph.trim() === '') {
                    lines.push('');
                    return;
                }
                
                // 处理每个段落，第一个段落的第一行考虑首行缩进
                let isFirstParaFirstLine = paraIndex === 0 && lines.length === 0;
                let currentLine = '';
                
                for (let i = 0; i < paragraph.length; i++) {
                    const char = paragraph[i];
                    const testLine = currentLine + char;
                    const currentMaxWidth = isFirstParaFirstLine ? firstLineMaxWidth : contentWidth;
                    const testWidth = this.measureTextWidth(testLine);
                    
                    // 严格截断逻辑：只要超出宽度就立即换行
                    if (testWidth > currentMaxWidth) {
                        if (currentLine) {
                            lines.push(currentLine);
                            currentLine = char;
                        } else {
                            // 即使是单个字符也强制截断（避免极端情况）
                            lines.push(char);
                            currentLine = '';
                        }
                        // 只有第一段第一行需要首行缩进
                        isFirstParaFirstLine = false;
                    } else {
                        currentLine = testLine;
                    }
                }
                
                if (currentLine) {
                    lines.push(currentLine);
                }
            });
        }
        
        // 限制最大行数
        let actualLines = lines;
        if (maxLines > 0 && lines.length > maxLines) {
            actualLines = lines.slice(0, maxLines);
            // 最后一行添加省略号（如果需要）
            if (config.overflow === 'ellipsis') {
                const lastLine = actualLines[actualLines.length - 1];
                let truncatedLine = lastLine;
                const currentMaxWidth = actualLines.length === 1 && textIndent > 0 ? firstLineMaxWidth : contentWidth;
                
                while (truncatedLine.length > 0 && 
                       this.measureTextWidth(truncatedLine + '...') > currentMaxWidth) {
                    truncatedLine = truncatedLine.slice(0, -1);
                }
                actualLines[actualLines.length - 1] = truncatedLine + '...';
            }
        }

        // 确定最终显示的行数
        let finalLineCount = actualLines.length;
        if (whiteSpace === 'nowrap' || isEllipsisOrClip) {
            finalLineCount = 1; // 强制单行高度
        }
        
        // 计算总高度（像素）
        const lineHeightPx = config.fontSize * lineHeight;
        const totalContentHeightPx = finalLineCount * lineHeightPx;
        const totalHeightPx = totalContentHeightPx + (padding || 0) * 2;
        
        // 恢复原始字体
        this.ctx.font = originalFont;
        
        // 转换为百分比（相对于画布高度）
        const heightPercent = (totalHeightPx / this.config.height) * 100;
        console.log(`计算高度 - 实际行数: ${actualLines.length}, 显示行数: ${finalLineCount}, 像素高度: ${totalHeightPx}, 百分比高度: ${heightPercent}%`);
        
        return heightPercent;
    }
    
    /**
     * 获取字体度量信息（ ascent, descent, 行高 等）
     * @param {string} font 字体字符串
     * @param {number} fontSize 字体大小
     * @returns {Object} 字体度量信息
     */
    getFontMetrics(font, fontSize) {
        const cacheKey = font;
        
        // 检查缓存
        if (this._fontMetricsCache.has(cacheKey)) {
            return this._fontMetricsCache.get(cacheKey);
        }
        
        // 保存当前状态
        const originalFont = this.ctx.font;
        const originalTextBaseline = this.ctx.textBaseline;
        
        // 设置测量环境
        this.ctx.font = font;
        this.ctx.textBaseline = 'top';
        
        // 创建一个参考文本（使用大写和小写字母以及descender）
        const referenceText = 'Hg';
        const textMetrics = this.ctx.measureText(referenceText);
        
        // 计算 ascent (基线到顶部的距离) 和 descent (基线到底部的距离)
        const ascent = textMetrics.actualBoundingBoxAscent;
        const descent = textMetrics.actualBoundingBoxDescent;
        const lineGap = 0; // 简化计算
        
        // 恢复原始状态
        this.ctx.font = originalFont;
        this.ctx.textBaseline = originalTextBaseline;
        
        // 计算实际行高
        const actualLineHeight = ascent + descent + lineGap;
        
        // 缓存结果
        const metrics = {
            ascent,
            descent,
            lineGap,
            actualLineHeight,
            fontSize
        };
        this._fontMetricsCache.set(cacheKey, metrics);
        
        return metrics;
    }
    
    /**
     * 添加元素（合并默认配置和自定义配置）
     * @param {string} elementName 元素名称
     * @param {Object} customConfig 自定义配置
     */
    addElement(elementName, customConfig) {
        if (!customConfig || !customConfig.text) {
            return;
        }
        
        const mergedConfig = this.mergeWithTemplate(elementName, customConfig);
        this.elements[elementName] = mergedConfig;
    }
    
    /**
     * 合并默认配置和自定义配置
     * @param {string} elementName 元素名称
     * @param {Object} customConfig 自定义配置
     * @returns {Object} 合并后的配置
     */
    mergeWithTemplate(elementName, customConfig) {
        const template = this.elementTemplates[elementName];
        if (!template) {
            return Object.assign({}, customConfig);
        }
        
        const merged = Object.assign({}, template, customConfig);
        merged.enabled = customConfig.enabled !== undefined ? customConfig.enabled : template.enabled;
        merged.autoPosition = customConfig.autoPosition !== undefined ? customConfig.autoPosition : template.autoPosition;
        return merged;
    }
    
    /**
     * 将值转换为像素值（支持百分比）
     * @param {string|number} value 值
     * @param {string} dimension 维度（'width' 或 'height'）
     * @returns {number} 像素值
     */
    parseValueToPixel(value, dimension) {
        dimension = dimension || 'width';
        if (typeof value === 'string' && value.includes('%')) {
            const percent = parseFloat(value) / 100;
            if (dimension === 'width') {
                return this.config.width * percent;
            } else {
                return this.config.height * percent;
            }
        }
        return parseFloat(value) || 0;
    }
    
    /**
     * 获取元素的实际像素坐标和尺寸
     * @param {Object} element 元素配置
     * @returns {Object} 包含位置和尺寸的对象
     */
    getElementLayout(element) {
        const x = this.parseValueToPixel(element.x, 'width');
        const y = this.parseValueToPixel(element.y, 'height');
        const width = this.parseValueToPixel(element.width, 'width');
        const padding = element.padding || 0;
        
        return {
            x,
            y,
            width,
            padding,
            contentWidth: width - padding * 2,
            startX: this.getTextStartX(x, width, element.textAlign, padding),
            // 计算首行缩进后的起始X
            firstLineStartX: element.textIndent ? this.getTextStartX(x, width, element.textAlign, padding) + element.textIndent : this.getTextStartX(x, width, element.textAlign, padding)
        };
    }
    
    /**
     * 根据对齐方式获取文本起始X坐标
     * @param {number} x 元素X坐标
     * @param {number} width 元素宽度
     * @param {string} textAlign 文本对齐方式
     * @param {number} padding 内边距
     * @returns {number} 文本起始X坐标
     */
    getTextStartX(x, width, textAlign, padding) {
        padding = padding || 0;
        switch (textAlign) {
            case 'left':
                return x + padding;
            case 'right':
                return x + width - padding;
            case 'center':
            default:
                return x + width / 2;
        }
    }
    
    /**
     * 绘制背景
     * @param {string|HTMLImageElement} background 背景图片
     */
    async drawBackground(background) {
        this.ctx.clearRect(0, 0, this.config.width, this.config.height);
        
        if (background) {
            try {
                const image = await this.loadImage(background);
                const padding = this.config.backgroundPadding || 0;
                const availableWidth = this.config.width - padding * 2;
                const availableHeight = this.config.height - padding * 2;
                
                const scale = Math.min(
                    availableWidth / image.width, 
                    availableHeight / image.height
                );
                
                const scaledWidth = image.width * scale;
                const scaledHeight = image.height * scale;
                const x = padding + (availableWidth - scaledWidth) / 2;
                const y = padding + (availableHeight - scaledHeight) / 2;
                
                this.ctx.drawImage(image, x, y, scaledWidth, scaledHeight);
            } catch (error) {
                console.warn('背景图片加载失败，使用背景颜色:', error);
                this.drawColorBackground();
            }
        } else {
            this.drawColorBackground();
        }
    }
    
    /**
     * 绘制颜色背景
     */
    drawColorBackground() {
        this.ctx.fillStyle = this.config.backgroundColor;
        this.ctx.fillRect(0, 0, this.config.width, this.config.height);
    }
    
    /**
     * 加载图片
     * @param {string|HTMLImageElement} source 图片源
     * @returns {Promise<HTMLImageElement>}
     */
    loadImage(source) {
        return new Promise((resolve, reject) => {
            if (typeof source === 'string') {
                const img = new Image();
                img.crossOrigin = 'anonymous';
                img.onload = () => resolve(img);
                img.onerror = reject;
                img.src = source;
            } else if (source instanceof HTMLImageElement) {
                if (source.complete) {
                    resolve(source);
                } else {
                    source.onload = () => resolve(source);
                    source.onerror = reject;
                }
            } else {
                reject(new Error('不支持的图片源类型'));
            }
        });
    }
    
    /**
     * 绘制所有元素
     */
    drawAllElements() {
        Object.keys(this.elements).forEach(elementName => {
            const element = this.elements[elementName];
            if (element.enabled !== false && element.text) {
                this.drawElement(element);
            }
        });
    }
    
    /**
     * 绘制单个元素
     * @param {Object} element 元素配置
     */
    drawElement(element) {
        if (!element.text) return;
        
        // 获取布局信息
        const layout = this.getElementLayout(element);
        
        // 构建字体字符串
        let fontStyle = '';
        if (element.bold) fontStyle += 'bold ';
        if (element.italic) fontStyle += 'italic ';
        
        this.ctx.font = `${fontStyle}${element.fontSize}px ${element.fontFamily}`;
        this.ctx.fillStyle = element.color;
        this.ctx.textBaseline = element.textBaseline;
        
        // 设置阴影
        if (element.shadow) {
            this.ctx.shadowColor = 'rgba(0, 0, 0, 0.5)';
            this.ctx.shadowBlur = 5;
            this.ctx.shadowOffsetX = 2;
            this.ctx.shadowOffsetY = 2;
        } else {
            this.ctx.shadowColor = 'transparent';
            this.ctx.shadowBlur = 0;
            this.ctx.shadowOffsetX = 0;
            this.ctx.shadowOffsetY = 0;
        }
        
        // 根据overflow策略绘制文本
        switch (element.overflow) {
            case 'ellipsis':
                this.drawTextWithEllipsis(element, layout);
                break;
            case 'clip':
                this.drawTextWithClip(element, layout);
                break;
            case 'wrap':
            default:
                this.drawTextWithWrap(element, layout);
                break;
        }
        
        // 重置阴影
        this.ctx.shadowColor = 'transparent';
        this.ctx.shadowBlur = 0;
        this.ctx.shadowOffsetX = 0;
        this.ctx.shadowOffsetY = 0;
    }
    
    /**
     * 测量文本宽度（缓存优化）
     * @param {string} text 文本
     * @returns {number} 文本宽度
     */
    measureTextWidth(text) {
        const cacheKey = `${this.ctx.font}|${text}`;
        if (this._textWidthCache.has(cacheKey)) {
            return this._textWidthCache.get(cacheKey);
        }
        
        const width = this.ctx.measureText(text).width;
        this._textWidthCache.set(cacheKey, width);
        return width;
    }
    
    /**
     * 绘制自动换行文本
     * @param {Object} element 元素配置
     * @param {Object} layout 布局信息
     */
    drawTextWithWrap(element, layout) {
        const { 
            text, 
            fontSize, 
            lineHeight, 
            maxLines, 
            textBaseline, 
            textAlign, 
            textIndent,
            textAlignLast,
            whiteSpace
        } = element;
        
        const { contentWidth, y, padding, x } = layout;
        
        let lines = [];
        
        if (whiteSpace === 'nowrap') {
            lines = text.split('\n');
        } else {
            lines = this.splitTextToLines(text, contentWidth, element);
        }
        
        // 限制最大行数
        if (maxLines > 0 && lines.length > maxLines) {
            lines = lines.slice(0, maxLines);
            if (lines.length > 0) {
                const lastLine = lines[lines.length - 1];
                let truncatedLine = lastLine;
                const currentMaxWidth = lines.length === 1 && textIndent > 0 ? contentWidth - textIndent : contentWidth;
                
                while (truncatedLine.length > 0 && 
                       this.measureTextWidth(truncatedLine + '...') > currentMaxWidth) {
                    truncatedLine = truncatedLine.slice(0, -1);
                }
                lines[lines.length - 1] = truncatedLine + '...';
            }
        }
        
        const lineHeightPx = fontSize * lineHeight;
        let startY = y + padding;
        
        // 根据文本基线调整起始位置
        switch (textBaseline) {
            case 'middle':
                startY -= (lines.length * lineHeightPx) / 2;
                break;
            case 'bottom':
                startY -= lines.length * lineHeightPx;
                break;
            case 'top':
            default:
                break;
        }
        
        // 绘制每一行
        lines.forEach((line, index) => {
            const isLastLine = index === lines.length - 1;
            
            // 计算每行的起始X坐标
            let lineStartX = x + padding;
            let lineContentWidth = contentWidth;
            
            // 首行缩进处理
            if (index === 0 && textIndent > 0) {
                if (textAlign === 'left' || textAlign === 'justify') {
                    lineStartX += textIndent;
                    lineContentWidth -= textIndent;
                }
            }
            
            // 根据对齐方式绘制文本
            if (textAlign === 'justify' && !isLastLine && line.trim()) {
                this.drawJustifiedText(line, lineStartX, startY + index * lineHeightPx, lineContentWidth);
            } else {
                const currentAlign = (textAlign === 'justify' && isLastLine) ? textAlignLast : textAlign;
                this.drawAlignedText(line, lineStartX, startY + index * lineHeightPx, lineContentWidth, currentAlign);
            }
        });
    }
    
    /**
     * 绘制对齐文本
     * @param {string} text 文本
     * @param {number} x 起始X坐标
     * @param {number} y Y坐标
     * @param {number} maxWidth 最大宽度
     * @param {string} align 对齐方式
     */
    drawAlignedText(text, x, y, maxWidth, align) {
        const originalAlign = this.ctx.textAlign;
        
        switch (align) {
            case 'left':
            case 'start':
                this.ctx.textAlign = 'left';
                this.ctx.fillText(text, x, y);
                break;
            case 'right':
            case 'end':
                this.ctx.textAlign = 'right';
                this.ctx.fillText(text, x + maxWidth, y);
                break;
            case 'center':
                this.ctx.textAlign = 'center';
                this.ctx.fillText(text, x + maxWidth / 2, y);
                break;
            default:
                this.ctx.textAlign = 'left';
                this.ctx.fillText(text, x, y);
        }
        
        this.ctx.textAlign = originalAlign;
    }
    
    /**
     * 绘制两端对齐的文本
     * @param {string} text 文本
     * @param {number} x 起始X坐标
     * @param {number} y Y坐标
     * @param {number} maxWidth 最大宽度
     */
    drawJustifiedText(text, x, y, maxWidth) {
        const words = text.split(/(\s+)/).filter(word => word.trim() !== '');
        if (words.length <= 1) {
            this.ctx.textAlign = 'left';
            this.ctx.fillText(text, x, y);
            return;
        }
        
        // 计算非空格字符总宽度
        let contentWidth = 0;
        let spaceCount = 0;
        for (const word of words) {
            if (word.trim() === '') {
                spaceCount++;
            } else {
                contentWidth += this.measureTextWidth(word);
            }
        }
        
        // 计算需要分配的空格总宽度
        const totalSpaceWidth = maxWidth - contentWidth;
        const spaceWidth = spaceCount > 0 ? totalSpaceWidth / spaceCount : 0;
        
        let currentX = x;
        
        // 绘制每个部分
        this.ctx.textAlign = 'left';
        for (let i = 0; i < words.length; i++) {
            const word = words[i];
            if (word.trim() === '') {
                currentX += spaceWidth;
            } else {
                this.ctx.fillText(word, currentX, y);
                currentX += this.measureTextWidth(word);
            }
        }
    }
    
    /**
     * 绘制省略号文本（修复首行缩进问题）
     * @param {Object} element 元素配置
     * @param {Object} layout 布局信息
     */
    drawTextWithEllipsis(element, layout) {
        const { text, textIndent, textAlign } = element;
        const { contentWidth, y, firstLineStartX } = layout;
        
        // 计算实际可用宽度（考虑首行缩进）
        const availableWidth = textIndent > 0 ? contentWidth - textIndent : contentWidth;
        
        let displayText = text;
        const ellipsis = '...';
        const ellipsisWidth = this.measureTextWidth(ellipsis);
        
        if (this.measureTextWidth(text) > availableWidth) {
            let truncatedText = text;
            while (truncatedText.length > 0 && 
                   this.measureTextWidth(truncatedText + ellipsis) > availableWidth) {
                truncatedText = truncatedText.slice(0, -1);
            }
            displayText = truncatedText + ellipsis;
        }
        
        // 使用考虑首行缩进的起始X坐标
        this.ctx.textAlign = textAlign === 'left' ? 'left' : this.ctx.textAlign;
        this.ctx.fillText(displayText, firstLineStartX, y);
    }
    
    /**
     * 绘制裁剪文本（修复首行缩进问题）
     * @param {Object} element 元素配置
     * @param {Object} layout 布局信息
     */
    drawTextWithClip(element, layout) {
        const { text, textIndent, fontSize } = element;
        const { x, y, width, padding, firstLineStartX } = layout;
        
        // 计算裁剪区域（考虑首行缩进）
        const clipWidth = textIndent > 0 ? width - padding * 2 - textIndent : width - padding * 2;
        const clipX = textIndent > 0 ? x + padding + textIndent : x + padding;
        
        this.ctx.save();
        this.ctx.beginPath();
        this.ctx.rect(clipX, y - padding, clipWidth, fontSize * 2);
        this.ctx.clip();
        this.ctx.textAlign = 'left';
        this.ctx.fillText(text, firstLineStartX, y);
        this.ctx.restore();
    }
    
    /**
     * 分割文本为适合宽度的行（严格按宽度截断，不考虑字符类型）
     * @param {string} text 文本
     * @param {number} maxWidth 最大宽度
     * @param {Object} element 元素配置
     * @returns {string[]} 分割后的行数组
     */
    splitTextToLines(text, maxWidth, element) {
        const paragraphs = text.split('\n');
        const lines = [];
        const textIndent = element.textIndent || 0;
        const firstLineMaxWidth = maxWidth - textIndent;
        const otherLinesMaxWidth = maxWidth;
        
        // 处理每个段落
        paragraphs.forEach((paragraph, paraIndex) => {
            if (paragraph.trim() === '') {
                lines.push('');
                return;
            }
            
            // 第一个段落的第一行需要考虑首行缩进
            // 修复：使用let声明变量，允许重新赋值
            let isFirstParaFirstLine = paraIndex === 0 && lines.length === 0;
            let currentLine = '';
            
            for (let i = 0; i < paragraph.length; i++) {
                const char = paragraph[i];
                const testLine = currentLine + char;
                const currentMaxWidth = isFirstParaFirstLine ? firstLineMaxWidth : otherLinesMaxWidth;
                const testWidth = this.measureTextWidth(testLine);
                
                // 严格判断：只要超出宽度就立即换行
                if (testWidth > currentMaxWidth) {
                    // 如果当前行不为空，添加到结果并开始新行
                    if (currentLine) {
                        lines.push(currentLine);
                        currentLine = char;
                    } else {
                        // 即使是单个字符也强制截断（避免极端情况）
                        lines.push(char);
                        currentLine = '';
                    }
                    // 只有第一段第一行需要首行缩进
                    isFirstParaFirstLine = false;
                } else {
                    currentLine = testLine;
                }
            }
            
            // 添加剩余内容
            if (currentLine) {
                lines.push(currentLine);
            }
        });
        
        return lines;
    }
    
    // 其他辅助方法
    getElementLayoutInfo(elementName) {
        if (this.elements[elementName]) {
            return this.getElementLayout(this.elements[elementName]);
        }
        return null;
    }
    
    updateElementConfig(elementName, config) {
        if (this.elements[elementName]) {
            this.elements[elementName] = Object.assign({}, this.elements[elementName], config);
        }
    }
    
    setElementTemplate(elementName, templateConfig) {
        if (this.elementTemplates[elementName]) {
            this.elementTemplates[elementName] = Object.assign({}, this.elementTemplates[elementName], templateConfig);
        }
    }
    
    setElementStyle(elementName, style) {
        if (this.elements[elementName]) {
            this.elements[elementName] = Object.assign({}, this.elements[elementName], style);
        }
    }
    
    setElementLayout(elementName, x, y, width) {
        if (this.elements[elementName]) {
            this.elements[elementName].x = x;
            this.elements[elementName].y = y;
            this.elements[elementName].width = width;
        }
    }
    
    setBackgroundPadding(padding) {
        this.config.backgroundPadding = padding;
    }
    
    getCanvas() {
        return this.canvas;
    }
    
    getBlob() {
        return new Promise((resolve) => {
            this.canvas.toBlob(resolve, 'image/png');
        });
    }
    
    async download(filename) {
        if (!filename) {
            filename = '结业证书_' + new Date().toLocaleString() + '.png';
        }
        const dataUrl = this.canvas.toDataURL('image/png');
        const link = document.createElement('a');
        link.download = filename;
        link.href = dataUrl;
        link.click();
    }
    
    setSize(width, height) {
        this.config.width = width;
        this.config.height = height;
        this.canvas.width = width;
        this.canvas.height = height;
    }
    
    previewTextLayout(elementName) {
        if (!this.elements[elementName]) return;
        
        const element = this.elements[elementName];
        const layout = this.getElementLayout(element);
        const testLines = this.splitTextToLines(element.text, layout.contentWidth, element);
        
        console.log(`元素 "${elementName}" 布局信息:`, {
            配置: {
                文本: element.text,
                位置: `${element.x}, ${element.y}`,
                宽度: element.width,
                对齐: element.textAlign,
                最后一行对齐: element.textAlignLast,
                首行缩进: element.textIndent,
                启用状态: element.enabled
            },
            实际像素: {
                x: layout.x,
                y: layout.y,
                宽度: layout.width,
                内容宽度: layout.contentWidth
            },
            文本测量: {
                单行宽度: this.measureTextWidth(element.text),
                分割行数: testLines.length,
                各行内容: testLines
            }
        });
    }
    
    destroy() {
        this.canvas.width = 0;
        this.canvas.height = 0;
        this.ctx = null;
        this.canvas = null;
        this._textWidthCache.clear();
        this._fontMetricsCache.clear();
    }
}

export default CanvasImageGenerator;

使用方法

基本使用

const generator = new CanvasImageGenerator();

// 生成图片
const imageDataUrl = await generator.generate({
    background: 'path/to/background.jpg',
    title: {
        text: '多内容模块示例'
    },
    contents: [
        {
            text: '这是第一个内容模块，包含较短的文本。',
            fontSize: 20
        },
        {
            text: '这是第二个内容模块，包含较长的文本内容。这个模块会自动计算高度，并基于上一个模块的底部位置进行精确定位，避免内容重叠问题。',
            fontSize: 18,
            lineHeight: 1.6
        },
        {
            text: '这是第三个内容模块，可以禁用自动定位，使用自定义位置。',
            autoPosition: false,
            x: '50%',
            y: '70%'
        }
    ],
    date: {
        text: '2023年10月15日'
    },
    unit: {
        text: '报告单位：技术部'
    }
});

// 在页面上显示
const img = document.createElement('img');
img.src = imageDataUrl;
document.body.appendChild(img);
高级使用
javascript
// 创建带初始配置的实例
const generator = new CanvasImageGenerator({
    width: 1000,
    height: 600,
    backgroundColor: '#2c3e50'
});

// 生成图片
const imageDataUrl = await generator.generate({
    background: 'https://example.com/background.jpg',
    title: {
        text: '多内容模块示例'
    },
    contents: [
        {
            text: '这是第一个内容模块，包含较短的文本。',
            fontSize: 20
        },
        {
            text: '这是第二个内容模块，包含较长的文本内容。这个模块会自动计算高度，并基于上一个模块的底部位置进行精确定位，避免内容重叠问题。',
            fontSize: 18,
            lineHeight: 1.6
        },
        {
            text: '这是第三个内容模块，可以禁用自动定位，使用自定义位置。',
            autoPosition: false,
            x: '50%',
            y: '70%'
        }
    ],
    date: {
        text: '2023年12月31日',
        fontSize: 24,
        color: '#f1c40f',
        x: 800,
        y: 500
    },
    unit: {
        text: '编制：市场部',
        fontSize: 20,
        color: '#f1c40f',
        x: 800,
        y: 540
    }
});

// 直接下载
await generator.download('年度报告.png');

链式调用模式

// 可以创建链式调用的包装函数
async function createCustomImage() {
    const generator = new CanvasImageGenerator();
    
    // 设置尺寸
    generator.setSize(1200, 800);
    
    // 生成并下载
    await generator.generate({
        background: 'background.jpg',
        title: { text: '自定义标题', fontSize: 72 },
        content: { text: '详细内容描述' },
        date: { text: '2024-01-01' },
        unit: { text: '单位：自定义' }
    });
    
    await generator.download('custom-image.png');
    
    // 清理资源
    generator.destroy();
}

在React/Vue中使用

// React组件中使用


function ImageGeneratorComponent() {
    const generateImage = async () => {
        const generator = new CanvasImageGenerator();
        
        try {
            const imageUrl = await generator.generate({
                background: '/assets/bg.jpg',
                title: { text: 'React生成的图片' },
                content: { text: '这是在React中生成的图片' },
                date: { text: new Date().toLocaleDateString() },
                unit: { text: '来源：React应用' }
            });
            
            // 更新state或直接使用
            setGeneratedImage(imageUrl);
        } catch (error) {
            console.error('生成失败:', error);
        }
    };
    
    return (
        <div>
            <button onClick={generateImage}>生成图片</button>
            {/* 显示生成的图片 */}
        </div>
    );
}