---
title: "UUPSUpgradeable"
type: concept
tags: []
last_updated: 2026-05-01
---

## Definition
UUPS（Universal Upgradeable Proxy Standard，EIP-1822）是一种智能合约可升级模式，通过代理合约（Proxy）将用户请求转发给实现合约（Implementation），实现合约可以独立升级而不改变代理地址。

## How It Works
```
User → Proxy (永恒地址) → Implementation v1 → Implementation v2 (升级后)
```

- **Proxy**：永恒地址，存储所有数据，持有用户资产
- **Implementation**：包含业务逻辑，可以随时替换
- **UUPS 特有**：升级逻辑嵌入在 Implementation 中（而非 Proxy 中）

## UUPS vs Transparent Proxy

| 维度 | UUPS | Transparent Proxy |
|------|------|-------------------|
| 升级逻辑位置 | Implementation | Proxy（Admin） |
| 部署 gas 成本 | 较低 | 较高（Admin check 每次调用） |
| Admin 权限 | 无（除非嵌入） | 必须由 Proxy Admin 管理 |
| 安全性 | 实现错误升级逻辑会导致 brick | Proxy 层更简单 |

## UUPS Implementation Pattern
```solidity
import {UUPSUpgradeable} from "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";

contract MyContractV1 is UUPSUpgradeable, Ownable {
    function _authorizeUpgrade(address) internal override onlyOwner {
        // 升级权限控制
    }
}
```

## 存储兼容性关键规则
- **永远不要删除或重新排序 storage 变量**——会破坏代理合约中的数据布局
- **只能在末尾添加新变量**——追加永远安全
- OpenZeppelin 提供 storage 布局验证工具

## Sources
- [[engineering-solidity-smart-contract-engineer]]
- [[OpenZeppelin]]